Skip to main content
Back to JavaScript

JavaScript Management API

These functions call the ThunderID management API to list, read, create, update, and delete applications, users, agents, and authorization details types. They take a fetch-compatible fetcher, so they run with any HTTP client or data fetching library. Requests are authorized with the signed-in user's access token, and the token needs the permissions the server requires for each resource.

The functions attach no token themselves. Pass a fetcher that adds the Authorization header, for example one built on ThunderIDJavaScriptClient.getAccessToken():

ts
import { getApplications, createUser } from '@thunderid/javascript'

// `client` is your initialized ThunderIDJavaScriptClient.
const authenticatedFetch = async (url: string, config: RequestInit): Promise<Response> =>
fetch(url, {
...config,
headers: {...config.headers, Authorization: `Bearer ${await client.getAccessToken()}`},
})

const {applications, totalResults} = await getApplications({
baseUrl: 'https://localhost:8090',
fetcher: authenticatedFetch,
limit: 10,
})

const user = await createUser({
baseUrl: 'https://localhost:8090',
fetcher: authenticatedFetch,
payload: {ouId: '<organization-unit-id>', type: 'customer', attributes: {username: 'alice'}},
})

In a React application, use the management hooks instead. They supply an authenticated fetcher for you.

Request Configuration​

Every function accepts these options alongside its own parameters. Other RequestInit options, such as headers and signal, pass through to the fetcher.

ParameterTypeRequiredDescription
baseUrlstringNoBase URL of the ThunderID resource server. The collection URL is derived as {baseUrl}/applications, {baseUrl}/users, {baseUrl}/agents, or {baseUrl}/authorization-detail-types.
urlstringNoAbsolute URL of the resource collection. Takes precedence over baseUrl. A single resource is addressed as {url}/{id}.
fetcher(url: string, config: RequestInit) => Promise<Response>NoPerforms the request. Defaults to the global fetch, which sends no access token, so pass a fetcher that attaches one.

One of baseUrl or url is required.

Applications​

FunctionRequestReturns
getApplications({limit, offset})GET /applications?limit=&offset=ApplicationListResponse
getApplication({applicationId})GET /applications/{applicationId}Application
createApplication({payload})POST /applicationsApplication
updateApplication({applicationId, payload})PUT /applications/{applicationId}Application
deleteApplication({applicationId})DELETE /applications/{applicationId}void

payload is a CreateApplicationRequest, which is an Application without id, createdAt, and updatedAt. An update replaces the application's mutable fields, so send the full application rather than only the changed fields.

ApplicationListResponse contains applications (BasicApplication[]), count, and totalResults.

Users​

FunctionRequestReturns
getUsers({limit, offset, filter})GET /users?limit=&offset=&filter=&include=displayManagedUserListResponse
getUser({userId})GET /users/{userId}?include=displayManagedUser
createUser({payload})POST /usersManagedUser
updateUser({userId, payload})PUT /users/{userId}ManagedUser
deleteUser({userId})DELETE /users/{userId}void

A ManagedUser is a user record on the server, with id, ouId, type, attributes, and the resolved display value. It is a different type from User, which describes the signed-in user.

PayloadFields
CreateManagedUserRequestouId (required), type (required), groups, attributes
UpdateManagedUserRequestouId, type, groups, attributes

ManagedUserListResponse contains users, count, startIndex, totalResults, and optional pagination links.

Agents​

FunctionRequestReturns
getAgents({limit, offset})GET /agents?limit=&offset=&include=displayAgentListResponse
getAgent({agentId})GET /agents/{agentId}?include=displayAgent
createAgent({payload})POST /agentsAgent
updateAgent({agentId, payload})PUT /agents/{agentId}Agent
deleteAgent({agentId})DELETE /agents/{agentId}void
PayloadFields
CreateAgentRequestouId, type, and name (required), description, logoUrl, owner, attributes, inboundAuthConfig
UpdateAgentRequestAny CreateAgentRequest field, plus allowedUserTypes, allowedAgentTypes, authFlowId, registrationFlowId, and isRegistrationFlowEnabled

The agent type is the handle of an agent type, and allowedUserTypes and allowedAgentTypes list user type and agent type handles. Set allowedAgentTypes to ["*"] to allow an agent of any agent type.

AgentListResponse contains agents (BasicAgent[]), count, startIndex, and totalResults.

Authorization Details Types​

An authorization details type defines what clients may request in RFC 9396 authorization details. The Console lists these types under Intents. For the schema, field policies, and processor settings, see Manage Intents.

FunctionRequestReturns
getAuthorizationDetailTypes({limit, offset})GET /authorization-detail-types?limit=&offset=AuthorizationDetailTypeListResponse
getAuthorizationDetailType({authorizationDetailTypeId})GET /authorization-detail-types/{authorizationDetailTypeId}AuthorizationDetailType
createAuthorizationDetailType({payload})POST /authorization-detail-typesAuthorizationDetailType
updateAuthorizationDetailType({authorizationDetailTypeId, payload})PUT /authorization-detail-types/{authorizationDetailTypeId}AuthorizationDetailType
deleteAuthorizationDetailType({authorizationDetailTypeId})DELETE /authorization-detail-types/{authorizationDetailTypeId}void

On a data plane, including the all-in-one server, no access token creates, updates, or deletes an authorization details type: the server answers 403, and the functions throw ThunderIDAPIError with the code <function>-ForbiddenError-001. Call these three against a control plane, or import the types. See Resources Imported Only With the Management API Key. getAuthorizationDetailTypes() and getAuthorizationDetailType() work with any token that may read them.

ts
import { createAuthorizationDetailType } from '@thunderid/javascript'

const accountType = await createAuthorizationDetailType({
baseUrl: 'https://localhost:8090',
fetcher: authenticatedFetch,
payload: {
type: 'account_information',
name: 'Account information',
schema: {type: 'object', properties: {accounts: {type: 'array', items: {type: 'string'}}}},
},
})

payload is an AuthorizationDetailTypeRequest:

FieldTypeRequiredDescription
typestringYesThe value clients send as the type of a detail. It cannot change after creation: an update with a different type fails with HTTP 400
namestringYesDisplay name of the type
schemaRecord<string, unknown>YesThe JSON Schema every detail of the type must conform to
descriptionstringNoDescription of the type
consentTemplatestringNoThe summary shown for a detail on the consent step
reusebooleanNoWhether an earlier approval may stand in for the consent prompt
processorAuthorizationDetailProcessorNoThe endpoint that approves and fills in each detail: endpoint and an optional authentication (type and properties)

An AuthorizationDetailType has the same fields, plus id, version, and isReadOnly, which is true for a type the API cannot update or delete: one declared in a configuration file, or one a control plane deployed. The server returns stored processor credentials masked.

AuthorizationDetailTypeListResponse contains types, count, startIndex, totalResults, and optional pagination links.

To read the types a client may request without an access token, use getSupportedAuthorizationDetailsTypes().

Flows and Connections​

These functions read the flows and connections an organization unit works with. Pass ouId to scope a request to one organization unit, which is what a delegated admin needs.

FunctionRequestReturns
getFlows({flowType, limit, offset, ouId})GET /flows?filter=&flowType=&limit=&offset=ManagedFlowListResponse
getFlow({flowId, ouId})GET /flows/{flowId}?ouId=ManagedFlowDefinition
getConnections({category, type, limit, offset, ouId})GET /connections?filter=&category=&limit=&offset=ConnectionListResponse, or ConnectionSummary[] when type is set
getFlowVariables({flowId, ouId})FlowVariables
updateFlowVariables({flowId, ouId, variables})FlowVariables
getFlowOverlayRules({flowId, ouId})The resolved overlay: what the unit may do with each variable

ouId changes each function as follows:

  • getFlows and getConnections list the flows or connections the unit owns, followed by the ones shared with it, instead of every one the caller can see. The unit is sent as the filter ouId eq "<id>". Each flow in the list carries isOwnedByOU, which is false for a flow shared with the unit. getConnections applies ouId only to the listing across every type.
  • getFlow returns the flow as the unit sees it. A flow shared with the unit comes back as its variables only. Leave ouId out for the whole definition when the caller can read the owning unit's flow. A caller confined to a unit the flow was shared with gets the shared view, without nodes, even without ouId.

updateFlowVariables replaces the values the unit holds, so a variable left out of variables returns to its default. The server validates every value before it writes any. See Flow Variables for helpers that read the definitions and validate values.

Management API on a Separate Host​

When the management API runs on a different host from the authorization server, pass the collection URL as url. To keep the URL in configuration instead, set endpoints.applications, endpoints.users, endpoints.agents, or endpoints.authorizationDetailTypes and read it with resolveResourceEndpoint, as the React hooks do. See Configuration.

ts
await deleteUser({
url: 'https://rs.example.com/users',
fetcher: authenticatedFetch,
userId: '<user-id>',
})

Cache Keys​

ApplicationQueryKeys, UserQueryKeys, and AgentQueryKeys name each resource for caching. The React hooks use them to refetch after a mutation. Reuse them as keys in your own data fetching cache.

ConstantKeys
ApplicationQueryKeysAPPLICATIONS ('applications'), APPLICATION ('application')
UserQueryKeysUSERS ('users'), USER ('user')
AgentQueryKeysAGENTS ('agents'), AGENT ('agent')

Flow resources have their own keys, described in Flow Variables.

Error Handling​

Every function throws ThunderIDAPIError. The code starts with the function name:

CodeCause
{function}-ValidationError-001url or baseUrl is not a valid URL. Thrown before any request is sent.
{function}-ValidationError-002The resource identifier is empty. Thrown before any request is sent.
{function}-ForbiddenError-001The server returned HTTP 403. The access token lacks permission for the operation.
{function}-NotFoundError-001The server returned HTTP 404. The resource does not exist.
{function}-ResponseError-001The server returned another non-2xx status.
{function}-NetworkError-001The request failed before a response arrived, or the response could not be parsed.
ts
import { getApplication, ThunderIDAPIError } from '@thunderid/javascript'

try {
await getApplication({baseUrl, fetcher, applicationId})
} catch (err) {
if (err instanceof ThunderIDAPIError && err.code === 'getApplication-NotFoundError-001') {
// Show a "not found" state.
}
}

Explore with AI

ThunderID LogoThunderID Logo

Product

DocsAPIsSDKs
© Copyright Linux Foundation Europe.For web site terms of use, trademark policy and other project policies please see https://linuxfoundation.eu/en/policies.