Update AppStore Settings

curl --request PATCH \
  --url https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "allowed_requester_group_uuids": [
    "4d5e6f70-8192-0123-def0-234567890123"
  ],
  "catalog_visibility": "visible",
  "in_app_store": true,
  "request_instructions": "Pick the role you need and say what it's for.",
  "time_based_access": {
    "default": "7 days",
    "options": [
      "7 days",
      "30 days"
    ]
  }
}
EOF

import requests

url = "https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings"

payload = {
    "allowed_requester_group_uuids": ["4d5e6f70-8192-0123-def0-234567890123"],
    "catalog_visibility": "visible",
    "in_app_store": True,
    "request_instructions": "Pick the role you need and say what it's for.",
    "time_based_access": {
        "default": "7 days",
        "options": ["7 days", "30 days"]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    allowed_requester_group_uuids: ['4d5e6f70-8192-0123-def0-234567890123'],
    catalog_visibility: 'visible',
    in_app_store: true,
    request_instructions: 'Pick the role you need and say what it\'s for.',
    time_based_access: {default: '7 days', options: ['7 days', '30 days']}
  })
};

fetch('https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'allowed_requester_group_uuids' => [
        '4d5e6f70-8192-0123-def0-234567890123'
    ],
    'catalog_visibility' => 'visible',
    'in_app_store' => true,
    'request_instructions' => 'Pick the role you need and say what it\'s for.',
    'time_based_access' => [
        'default' => '7 days',
        'options' => [
                '7 days',
                '30 days'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings"

	payload := strings.NewReader("{\n  \"allowed_requester_group_uuids\": [\n    \"4d5e6f70-8192-0123-def0-234567890123\"\n  ],\n  \"catalog_visibility\": \"visible\",\n  \"in_app_store\": true,\n  \"request_instructions\": \"Pick the role you need and say what it's for.\",\n  \"time_based_access\": {\n    \"default\": \"7 days\",\n    \"options\": [\n      \"7 days\",\n      \"30 days\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"allowed_requester_group_uuids\": [\n    \"4d5e6f70-8192-0123-def0-234567890123\"\n  ],\n  \"catalog_visibility\": \"visible\",\n  \"in_app_store\": true,\n  \"request_instructions\": \"Pick the role you need and say what it's for.\",\n  \"time_based_access\": {\n    \"default\": \"7 days\",\n    \"options\": [\n      \"7 days\",\n      \"30 days\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"allowed_requester_group_uuids\": [\n    \"4d5e6f70-8192-0123-def0-234567890123\"\n  ],\n  \"catalog_visibility\": \"visible\",\n  \"in_app_store\": true,\n  \"request_instructions\": \"Pick the role you need and say what it's for.\",\n  \"time_based_access\": {\n    \"default\": \"7 days\",\n    \"options\": [\n      \"7 days\",\n      \"30 days\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "allow_permission_selection": true,
  "allow_multiple_permission_selection": true,
  "time_based_access": {
    "options": [
      {
        "label": "<string>",
        "value_seconds": 123
      }
    ],
    "default": "<string>"
  },
  "in_app_store": true,
  "catalog_visibility": "visible",
  "request_instructions": "<string>",
  "allowed_requester_group_uuids": [
    "<string>"
  ],
  "request_validation_webhook_uuid": "<string>",
  "redirect_url": "<string>",
  "default_entitlement": {
    "id": "<string>"
  },
  "custom_intake_fields": [
    {
      "reference_key": "<string>",
      "field_type": "text",
      "prompt": "<string>",
      "is_required": true,
      "description": "<string>",
      "dropdown_options": [
        "<string>"
      ]
    }
  ]
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Apps

Update AppStore Settings

Update an app’s AppStore configuration.

This is a merge patch: a field you omit keeps its current value, and a field you send as null is cleared. in_app_store, catalog_visibility, allow_permission_selection and allow_multiple_permission_selection always hold a value, so sending null for one of them returns 400. List fields such as allowed_requester_group_uuids and custom_intake_fields replace their contents rather than merging into them.

A custom_intake_fields list the app cannot take returns 400 appstore_settings.custom_intake_fields_invalid with every problem listed in error.errors, each pointing at the field by position, such as custom_intake_fields[2].reference_key.

PATCH

apps

{app_uuid}

appstore-settings

Update AppStore Settings

curl --request PATCH \
  --url https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "allowed_requester_group_uuids": [
    "4d5e6f70-8192-0123-def0-234567890123"
  ],
  "catalog_visibility": "visible",
  "in_app_store": true,
  "request_instructions": "Pick the role you need and say what it's for.",
  "time_based_access": {
    "default": "7 days",
    "options": [
      "7 days",
      "30 days"
    ]
  }
}
EOF

import requests

url = "https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings"

payload = {
    "allowed_requester_group_uuids": ["4d5e6f70-8192-0123-def0-234567890123"],
    "catalog_visibility": "visible",
    "in_app_store": True,
    "request_instructions": "Pick the role you need and say what it's for.",
    "time_based_access": {
        "default": "7 days",
        "options": ["7 days", "30 days"]
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    allowed_requester_group_uuids: ['4d5e6f70-8192-0123-def0-234567890123'],
    catalog_visibility: 'visible',
    in_app_store: true,
    request_instructions: 'Pick the role you need and say what it\'s for.',
    time_based_access: {default: '7 days', options: ['7 days', '30 days']}
  })
};

fetch('https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'allowed_requester_group_uuids' => [
        '4d5e6f70-8192-0123-def0-234567890123'
    ],
    'catalog_visibility' => 'visible',
    'in_app_store' => true,
    'request_instructions' => 'Pick the role you need and say what it\'s for.',
    'time_based_access' => [
        'default' => '7 days',
        'options' => [
                '7 days',
                '30 days'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings"

	payload := strings.NewReader("{\n  \"allowed_requester_group_uuids\": [\n    \"4d5e6f70-8192-0123-def0-234567890123\"\n  ],\n  \"catalog_visibility\": \"visible\",\n  \"in_app_store\": true,\n  \"request_instructions\": \"Pick the role you need and say what it's for.\",\n  \"time_based_access\": {\n    \"default\": \"7 days\",\n    \"options\": [\n      \"7 days\",\n      \"30 days\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"allowed_requester_group_uuids\": [\n    \"4d5e6f70-8192-0123-def0-234567890123\"\n  ],\n  \"catalog_visibility\": \"visible\",\n  \"in_app_store\": true,\n  \"request_instructions\": \"Pick the role you need and say what it's for.\",\n  \"time_based_access\": {\n    \"default\": \"7 days\",\n    \"options\": [\n      \"7 days\",\n      \"30 days\"\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lumos.com/v1/apps/{app_uuid}/appstore-settings")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"allowed_requester_group_uuids\": [\n    \"4d5e6f70-8192-0123-def0-234567890123\"\n  ],\n  \"catalog_visibility\": \"visible\",\n  \"in_app_store\": true,\n  \"request_instructions\": \"Pick the role you need and say what it's for.\",\n  \"time_based_access\": {\n    \"default\": \"7 days\",\n    \"options\": [\n      \"7 days\",\n      \"30 days\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "allow_permission_selection": true,
  "allow_multiple_permission_selection": true,
  "time_based_access": {
    "options": [
      {
        "label": "<string>",
        "value_seconds": 123
      }
    ],
    "default": "<string>"
  },
  "in_app_store": true,
  "catalog_visibility": "visible",
  "request_instructions": "<string>",
  "allowed_requester_group_uuids": [
    "<string>"
  ],
  "request_validation_webhook_uuid": "<string>",
  "redirect_url": "<string>",
  "default_entitlement": {
    "id": "<string>"
  },
  "custom_intake_fields": [
    {
      "reference_key": "<string>",
      "field_type": "text",
      "prompt": "<string>",
      "is_required": true,
      "description": "<string>",
      "dropdown_options": [
        "<string>"
      ]
    }
  ]
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

{
  "error": {
    "detail": "<string>",
    "type": "validation",
    "code": "<string>",
    "errors": [
      {
        "field": "<string>",
        "code": "<string>",
        "message": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

app_uuid

string

required

The app's ID, which GET /v1/apps returns as id.

Body

application/json

in_app_store

boolean

Set to true to list this app in the AppStore catalog.

catalog_visibility

enum<string>

Visibility within the catalog. "visible", "search-only", or "hidden". Omit to leave unchanged.

Available options:

visible,

search-only,

hidden

request_instructions

string | null

Custom instructions shown on the access-request form. Null clears any existing instructions.

allow_permission_selection

boolean

When true, requesters may select which entitlement to request. When false, the default entitlement is used automatically and only approvers can change it. Omit to leave unchanged.

allow_multiple_permission_selection

boolean

When true, requesters may select more than one entitlement per request. Omit to leave unchanged.

allowed_requester_group_uuids

string[] | null

UUIDs of groups whose members may request this app. Null or an empty list removes the restriction, so everyone in your organization can request the app.

time_based_access

TimeBasedAccessPatchInput · object | null

Time-based access configuration. Omit to leave all sub-fields unchanged.

Show child attributes

request_validation_webhook_uuid

string | null

UUID of the inline webhook to use for request validation. Null clears any existing webhook.

redirect_url

string | null

If set, requesting this app redirects the user to this URL instead of going through the normal access-request flow. Send null to clear an existing redirect; omit the field to leave it unchanged. An empty string is rejected. Max 2048 characters.

Required string length: 1 - 2048

default_entitlement

EntitlementRefInput · object | null

Entitlement to pre-select on the access-request form. Must belong to this app. Null clears the pre-selection. Omit to leave unchanged.

Show child attributes

custom_intake_fields

CustomIntakeFieldPatchInput · object[] | null

The complete desired custom intake field list, matched by reference_key. Fields you omit from the list are deleted. Null or an empty list deletes all of them. Omit this property to leave them unchanged.

Maximum array length: 50

Show child attributes

Response

Successful Response

allow_permission_selection

boolean

required

When true, requesters may select which entitlement to request. When false, the default entitlement is used automatically and only approvers can change it. An app that was never configured reports the value Lumos applies when validating its access requests, which may be false.

allow_multiple_permission_selection

boolean

required

When true, requesters may select more than one entitlement in a single request.

time_based_access

TimeBasedAccess · object

required

Time-based access configuration for this app.

Show child attributes

in_app_store

boolean

required

Whether this app is listed in the AppStore catalog.

catalog_visibility

enum<string>

required

Visibility of the app within the catalog. "visible" — shown in browse and search; "search-only" — returned only by search, not in browse; "hidden" — enrolled but not visible to requesters.

Available options:

visible,

search-only,

hidden

request_instructions

string | null

Custom instructions shown to a requester when they open the access-request form. Null means no custom instructions are set.

allowed_requester_group_uuids

string[] | null

UUIDs of the groups whose members may request this app. Null means everyone in your organization can request the app.

request_validation_webhook_uuid

string | null

UUID of the inline webhook called to validate access requests before approval. Null means no validation webhook is configured.

redirect_url

string | null

If set, requesting this app redirects the user to this URL instead of going through the normal access-request flow. Null means no redirect is configured. Max 2048 characters.

Maximum string length: 2048

default_entitlement

EntitlementRef · object | null

The entitlement pre-selected by default when a user opens the request form. Null means no default is set.

Show child attributes

custom_intake_fields

CustomIntakeField · object[] | null

Custom form questions shown to requesters before they submit an access request. Null means no custom fields are configured.

Show child attributes

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

Update AppStore Settings

Authorizations

Path Parameters

Body

Response