Get Subject

curl --request GET \
  --url https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}', 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-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "<string>",
  "subject_type": "account",
  "decision": "approve-access",
  "account_name": "<string>",
  "identity": {
    "id": "<string>",
    "email": "<string>",
    "given_name": "<string>",
    "family_name": "<string>",
    "status": "staged"
  },
  "reviewers": [
    {
      "id": "<string>",
      "group_id": "<string>",
      "group_name": "<string>",
      "email": "<string>",
      "given_name": "<string>",
      "family_name": "<string>"
    }
  ],
  "entitlement": {
    "id": "<string>",
    "label": "<string>",
    "type": "<string>"
  },
  "decided_by": {
    "id": "<string>",
    "email": "<string>",
    "given_name": "<string>",
    "family_name": "<string>",
    "status": "staged"
  },
  "decided_at": "2023-11-07T05:31:56Z",
  "note": "<string>",
  "removal": {
    "status": "in-progress",
    "method": "automated",
    "assignees": [
      {
        "id": "<string>",
        "group_id": "<string>",
        "group_name": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>"
      }
    ],
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "itsm_ticket": {
      "external_id": "<string>",
      "url": "<string>"
    }
  },
  "is_evidence_attached": true,
  "evidence_required_by": "review-setting-all-removals",
  "evidence": [
    {
      "filename": "<string>",
      "uploaded_at": "2023-11-07T05:31:56Z",
      "content_type": "<string>",
      "description": "<string>",
      "uploaded_by": {
        "id": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "status": "staged"
      }
    }
  ],
  "ai_recommendation": {
    "decision": "auto-approve",
    "decision_category": "<string>",
    "reasoning": "<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 Reviews

Get Subject

Read one subject: what is being reviewed, who is reviewing it, what they decided, and what removal that decision led to.

What a subject is follows from the app review’s type — an accounts review reviews accounts, an entitlements review reviews the entitlements an account holds — and subject_type says which. An entitlement subject also names the account it belongs to, so one shape serves both.

removal.status is current even while the removal runs. Evidence is reported beside removal rather than in it (is_evidence_attached, evidence_required_by, and the files under expand=evidence), since an approved subject can owe evidence too.

removal.error says which capability failed and what the integration reported. It does not say whether retrying will help; a removal waiting on a person clears only once that person acts.

GET

access-reviews

{review_uuid}

apps

{app_review_uuid}

subjects

{subject_uuid}

Get Subject

curl --request GET \
  --url https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid} \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}', 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-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.lumos.com/v1/access-reviews/{review_uuid}/apps/{app_review_uuid}/subjects/{subject_uuid}")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "id": "<string>",
  "subject_type": "account",
  "decision": "approve-access",
  "account_name": "<string>",
  "identity": {
    "id": "<string>",
    "email": "<string>",
    "given_name": "<string>",
    "family_name": "<string>",
    "status": "staged"
  },
  "reviewers": [
    {
      "id": "<string>",
      "group_id": "<string>",
      "group_name": "<string>",
      "email": "<string>",
      "given_name": "<string>",
      "family_name": "<string>"
    }
  ],
  "entitlement": {
    "id": "<string>",
    "label": "<string>",
    "type": "<string>"
  },
  "decided_by": {
    "id": "<string>",
    "email": "<string>",
    "given_name": "<string>",
    "family_name": "<string>",
    "status": "staged"
  },
  "decided_at": "2023-11-07T05:31:56Z",
  "note": "<string>",
  "removal": {
    "status": "in-progress",
    "method": "automated",
    "assignees": [
      {
        "id": "<string>",
        "group_id": "<string>",
        "group_name": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>"
      }
    ],
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "itsm_ticket": {
      "external_id": "<string>",
      "url": "<string>"
    }
  },
  "is_evidence_attached": true,
  "evidence_required_by": "review-setting-all-removals",
  "evidence": [
    {
      "filename": "<string>",
      "uploaded_at": "2023-11-07T05:31:56Z",
      "content_type": "<string>",
      "description": "<string>",
      "uploaded_by": {
        "id": "<string>",
        "email": "<string>",
        "given_name": "<string>",
        "family_name": "<string>",
        "status": "staged"
      }
    }
  ],
  "ai_recommendation": {
    "decision": "auto-approve",
    "decision_category": "<string>",
    "reasoning": "<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

review_uuid

string

required

The access review's ID.

app_review_uuid

string

required

The app review's ID. An app review is one app within the access review that review_uuid names.

subject_uuid

string

required

The subject's ID. A subject is one thing under review in the app review that app_review_uuid names: an account, or one entitlement an account holds.

Query Parameters

expand

string[] | null

Comma-separated related data to load: ai_recommendation, evidence, removal.itsm_ticket. A field not asked for is absent from the response rather than null.

Response

Successful Response

One thing under review: an account, or one of an account's entitlements.

string

required

The subject's ID.

subject_type

enum<string>

required

Whether this subject is an account or one entitlement held by an account. Follows from the app review's type, so every subject under one app review carries the same value.

Available options:

account,

account-entitlement

decision

enum<string>

required

What the reviewer decided. pending until someone decides.

Available options:

approve-access,

modify-access,

pending,

reject-access,

reviewing-permissions

account_name

string | null

The account's name in the app being reviewed.

identity

User · object | null

The Lumos user the account belongs to. Null for an account that matched no user — an unmatched account is still reviewed.

Show child attributes

reviewers

SubjectAssignee · object[]

Who is assigned to decide this subject. Empty before reviewers are assigned.

Show child attributes

entitlement

SubjectEntitlement · object | null

The entitlement under review. Present only when subject_type is account-entitlement.

Show child attributes

decided_by

User · object | null

Who made the decision.

Show child attributes

decided_at

string<date-time> | null

When the decision was made.

note

string | null

The note the reviewer left for the auditor alongside the decision.

removal

SubjectRemoval · object | null

The removal this decision led to. Null when the decision leaves the access in place, or when removals have not started.

Show child attributes

is_evidence_attached

boolean | null

Whether any evidence is attached to this subject. Whether any is owed is evidence_required_by.

evidence_required_by

enum<string> | null

Why evidence is owed, as the highest-ranked reason that applies: review-setting-all-removals when the app review asks for evidence on every removal, decision-reason when the decision's reason does, manual-action when a person acted on the removal or still must, no-removal-request when no workflow could carry the removal. Null when nothing asks for evidence. Read apart from removal, so an approved subject whose decision reason asks for evidence carries it too.

Available options:

review-setting-all-removals,

decision-reason,

manual-action,

no-removal-request

evidence

SubjectEvidence · object[] | null

Files attached as evidence for this subject, identifying fields only and no download link. Requires expand=evidence.

Show child attributes

ai_recommendation

AiRecommendation · object | null

What AI Assist recommended for this subject, if it reached one. Requires expand=ai_recommendation.

Show child attributes

Quick Start

Lumos API

API Reference

Guides

Migrate from v0

Lumos Connectors

Webhooks

Tools

Get Subject

Authorizations

Path Parameters

Query Parameters

Response