Create Access Request

curl --request POST \
  --url https://api.lumos.com/v1/access-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "access_length": "7 days",
  "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "business_justification": "I review pull requests for the payments service.",
  "entitlement_ids": [
    "2b3c4d5e-6f70-8901-bcde-f12345678901"
  ]
}
'

import requests

url = "https://api.lumos.com/v1/access-requests"

payload = {
    "access_length": "7 days",
    "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "business_justification": "I review pull requests for the payments service.",
    "entitlement_ids": ["2b3c4d5e-6f70-8901-bcde-f12345678901"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    access_length: '7 days',
    app_id: '1a2b3c4d-5e6f-7890-abcd-ef1234567890',
    business_justification: 'I review pull requests for the payments service.',
    entitlement_ids: ['2b3c4d5e-6f70-8901-bcde-f12345678901']
  })
};

fetch('https://api.lumos.com/v1/access-requests', 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/access-requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'access_length' => '7 days',
    'app_id' => '1a2b3c4d-5e6f-7890-abcd-ef1234567890',
    'business_justification' => 'I review pull requests for the payments service.',
    'entitlement_ids' => [
        '2b3c4d5e-6f70-8901-bcde-f12345678901'
    ]
  ]),
  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/access-requests"

	payload := strings.NewReader("{\n  \"access_length\": \"7 days\",\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"business_justification\": \"I review pull requests for the payments service.\",\n  \"entitlement_ids\": [\n    \"2b3c4d5e-6f70-8901-bcde-f12345678901\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.lumos.com/v1/access-requests")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access_length\": \"7 days\",\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"business_justification\": \"I review pull requests for the payments service.\",\n  \"entitlement_ids\": [\n    \"2b3c4d5e-6f70-8901-bcde-f12345678901\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lumos.com/v1/access-requests")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access_length\": \"7 days\",\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"business_justification\": \"I review pull requests for the payments service.\",\n  \"entitlement_ids\": [\n    \"2b3c4d5e-6f70-8901-bcde-f12345678901\"\n  ]\n}"

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

{
  "access_requests": [
    {
      "id": "<string>",
      "app_id": "<string>",
      "app_name": "<string>",
      "target_user": {
        "id": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "status": "staged"
      },
      "status": "pending",
      "requester_user": {
        "id": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "status": "staged"
      },
      "supporter_user": {
        "id": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "status": "staged"
      },
      "notes": {},
      "expires_at": "2023-11-07T05:31:56Z",
      "expiration_in_seconds": 123,
      "requested_at": "2023-11-07T05:31:56Z",
      "entitlements": [
        {
          "id": "<string>",
          "label": "<string>"
        }
      ],
      "tasks": [
        {
          "id": "<string>",
          "type": "access-request-approval",
          "category": "manager-approval",
          "status": "pending",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "description": "<string>",
          "instructions": "<string>",
          "product_area": "access-reviews",
          "app": {
            "id": "<string>"
          },
          "target_user": {
            "id": "<string>",
            "email": "<string>",
            "given_name": "<string>",
            "family_name": "<string>",
            "status": "staged"
          },
          "resolved_by": {
            "id": "<string>",
            "email": "<string>",
            "given_name": "<string>",
            "family_name": "<string>",
            "status": "staged"
          },
          "assignees": [
            {
              "id": "<string>",
              "type": "user",
              "name": "<string>",
              "email": "<string>"
            }
          ],
          "actions": [
            {
              "action_type": "<string>",
              "transitions": [
                {
                  "transition_to": "pending"
                }
              ]
            }
          ],
          "comments": [
            {
              "body": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "created_by": {
                "id": "<string>",
                "email": "<string>",
                "given_name": "<string>",
                "family_name": "<string>",
                "status": "staged"
              }
            }
          ],
          "access_request_id": "<string>",
          "entitlement_id": "<string>"
        }
      ],
      "custom_fields": [
        {
          "prompt": "<string>",
          "reference_key": "<string>",
          "response": "<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>"
      }
    ]
  }
}

Access Requests

Create Access Request

Create a request for access to an app, or to specific entitlements on it, for you or for target_user_id. One submission can create several requests, so the 201 response lists them in access_requests.

Name entitlements in entitlement_ids by Entitlement UUID. An unknown ID returns 404 access_request.entitlement_not_found. An entitlement you can’t request on app_id returns 400 access_request.entitlement_not_requestable.

Answer the app’s custom intake fields in custom_fields, keyed by reference_key. A missing required answer, an unknown key, an answer over 500 characters, or a dropdown answer that is not one of its options returns 400 access_request.custom_fields_invalid, with every problem listed in error.errors as custom_fields.<reference_key>.

Any other refusal returns 400 access_request.<reason>, where the reason is one of invalid, not_requestable, entitlement_invalid, access_length_invalid, expiration_invalid, itsm_ticket_id_required, missing_fields, rejected_by_webhook.

POST

access-requests

Create Access Request

curl --request POST \
  --url https://api.lumos.com/v1/access-requests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "access_length": "7 days",
  "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
  "business_justification": "I review pull requests for the payments service.",
  "entitlement_ids": [
    "2b3c4d5e-6f70-8901-bcde-f12345678901"
  ]
}
'

import requests

url = "https://api.lumos.com/v1/access-requests"

payload = {
    "access_length": "7 days",
    "app_id": "1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "business_justification": "I review pull requests for the payments service.",
    "entitlement_ids": ["2b3c4d5e-6f70-8901-bcde-f12345678901"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    access_length: '7 days',
    app_id: '1a2b3c4d-5e6f-7890-abcd-ef1234567890',
    business_justification: 'I review pull requests for the payments service.',
    entitlement_ids: ['2b3c4d5e-6f70-8901-bcde-f12345678901']
  })
};

fetch('https://api.lumos.com/v1/access-requests', 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/access-requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'access_length' => '7 days',
    'app_id' => '1a2b3c4d-5e6f-7890-abcd-ef1234567890',
    'business_justification' => 'I review pull requests for the payments service.',
    'entitlement_ids' => [
        '2b3c4d5e-6f70-8901-bcde-f12345678901'
    ]
  ]),
  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/access-requests"

	payload := strings.NewReader("{\n  \"access_length\": \"7 days\",\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"business_justification\": \"I review pull requests for the payments service.\",\n  \"entitlement_ids\": [\n    \"2b3c4d5e-6f70-8901-bcde-f12345678901\"\n  ]\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.lumos.com/v1/access-requests")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"access_length\": \"7 days\",\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"business_justification\": \"I review pull requests for the payments service.\",\n  \"entitlement_ids\": [\n    \"2b3c4d5e-6f70-8901-bcde-f12345678901\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lumos.com/v1/access-requests")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"access_length\": \"7 days\",\n  \"app_id\": \"1a2b3c4d-5e6f-7890-abcd-ef1234567890\",\n  \"business_justification\": \"I review pull requests for the payments service.\",\n  \"entitlement_ids\": [\n    \"2b3c4d5e-6f70-8901-bcde-f12345678901\"\n  ]\n}"

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

{
  "access_requests": [
    {
      "id": "<string>",
      "app_id": "<string>",
      "app_name": "<string>",
      "target_user": {
        "id": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "status": "staged"
      },
      "status": "pending",
      "requester_user": {
        "id": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "status": "staged"
      },
      "supporter_user": {
        "id": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "status": "staged"
      },
      "notes": {},
      "expires_at": "2023-11-07T05:31:56Z",
      "expiration_in_seconds": 123,
      "requested_at": "2023-11-07T05:31:56Z",
      "entitlements": [
        {
          "id": "<string>",
          "label": "<string>"
        }
      ],
      "tasks": [
        {
          "id": "<string>",
          "type": "access-request-approval",
          "category": "manager-approval",
          "status": "pending",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "description": "<string>",
          "instructions": "<string>",
          "product_area": "access-reviews",
          "app": {
            "id": "<string>"
          },
          "target_user": {
            "id": "<string>",
            "email": "<string>",
            "given_name": "<string>",
            "family_name": "<string>",
            "status": "staged"
          },
          "resolved_by": {
            "id": "<string>",
            "email": "<string>",
            "given_name": "<string>",
            "family_name": "<string>",
            "status": "staged"
          },
          "assignees": [
            {
              "id": "<string>",
              "type": "user",
              "name": "<string>",
              "email": "<string>"
            }
          ],
          "actions": [
            {
              "action_type": "<string>",
              "transitions": [
                {
                  "transition_to": "pending"
                }
              ]
            }
          ],
          "comments": [
            {
              "body": "<string>",
              "created_at": "2023-11-07T05:31:56Z",
              "created_by": {
                "id": "<string>",
                "email": "<string>",
                "given_name": "<string>",
                "family_name": "<string>",
                "status": "staged"
              }
            }
          ],
          "access_request_id": "<string>",
          "entitlement_id": "<string>"
        }
      ],
      "custom_fields": [
        {
          "prompt": "<string>",
          "reference_key": "<string>",
          "response": "<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.

Body

application/json

app_id

string

required

The UUID of the app to request access to.

requester_user_id

string | null

Override the user who made the request. If omitted, use the current user. Only organization admins may send this field; any other caller is refused with a 403.

target_user_id

string | null

User to request access for. If omitted, request for the current user.

note

string | null

[Deprecated - use business_justification] Why the user needs access.

business_justification

string | null

Why the user needs access.

expiration_in_seconds

integer | null

Once granted, how long the access should last, in seconds. The value must equal one of the app's time-based access options (when requesting entitlements, one that all of them offer) and be at least 30 minutes; anything else is rejected with 400. Omit it for permanent access, which works only if the app offers Unlimited. access_length names the same options by label and is the easier field to use; sending both returns 400.

access_length

string | null

Once granted, how long the access should last. Omitting it means permanent access, which works only if the app offers Unlimited. All possible values are '2 hours', '4 hours', '8 hours', '12 hours', '1 day', '2 days', '3 days', '7 days', '14 days', '30 days', '90 days', 'Unlimited', but the exact options depend on the settings of the app and entitlements. expiration_in_seconds names the same options in seconds; sending both returns 400.

entitlement_ids

string[] | null

Entitlement UUIDs to request, as /v1/entitlements returns them. Each must be requestable on app_id. Omit this to just request access to the app.

custom_fields

Custom Fields · object | null

Answers to the app's custom intake fields, keyed by reference_key. GET /v1/apps/{app_id}/appstore-settings lists the fields with their keys, required flags and dropdown options. Every required field needs a non-blank answer, and a dropdown answer must match one of its options exactly. Problems return 400 access_request.custom_fields_invalid with one entry per field in errors.

Show child attributes

Response

Successful Response

access_requests

AccessRequest · object[]

required

The access requests created. One submission fans out into one request per app, so this is a list even when a single app was requested.

Show child attributes

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

Create Access Request

Authorizations

Body

Response