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():
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
baseUrl | string | No | Base URL of the ThunderID resource server. The collection URL is derived as {baseUrl}/applications, {baseUrl}/users, {baseUrl}/agents, or {baseUrl}/authorization-detail-types. |
url | string | No | Absolute URL of the resource collection. Takes precedence over baseUrl. A single resource is addressed as {url}/{id}. |
fetcher | (url: string, config: RequestInit) => Promise<Response> | No | Performs 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
| Function | Request | Returns |
|---|---|---|
getApplications({limit, offset}) | GET /applications?limit=&offset= | ApplicationListResponse |
getApplication({applicationId}) | GET /applications/{applicationId} | Application |
createApplication({payload}) | POST /applications | Application |
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
| Function | Request | Returns |
|---|---|---|
getUsers({limit, offset, filter}) | GET /users?limit=&offset=&filter=&include=display | ManagedUserListResponse |
getUser({userId}) | GET /users/{userId}?include=display | ManagedUser |
createUser({payload}) | POST /users | ManagedUser |
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.
| Payload | Fields |
|---|---|
CreateManagedUserRequest | ouId (required), type (required), groups, attributes |
UpdateManagedUserRequest | ouId, type, groups, attributes |
ManagedUserListResponse contains users, count, startIndex, totalResults, and optional pagination links.
Agents
| Function | Request | Returns |
|---|---|---|
getAgents({limit, offset}) | GET /agents?limit=&offset=&include=display | AgentListResponse |
getAgent({agentId}) | GET /agents/{agentId}?include=display | Agent |
createAgent({payload}) | POST /agents | Agent |
updateAgent({agentId, payload}) | PUT /agents/{agentId} | Agent |
deleteAgent({agentId}) | DELETE /agents/{agentId} | void |
| Payload | Fields |
|---|---|
CreateAgentRequest | ouId, type, and name (required), description, logoUrl, owner, attributes, inboundAuthConfig |
UpdateAgentRequest | Any 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.
| Function | Request | Returns |
|---|---|---|
getAuthorizationDetailTypes({limit, offset}) | GET /authorization-detail-types?limit=&offset= | AuthorizationDetailTypeListResponse |
getAuthorizationDetailType({authorizationDetailTypeId}) | GET /authorization-detail-types/{authorizationDetailTypeId} | AuthorizationDetailType |
createAuthorizationDetailType({payload}) | POST /authorization-detail-types | AuthorizationDetailType |
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.
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:
| Field | Type | Required | Description |
|---|---|---|---|
type | string | Yes | The value clients send as the type of a detail. It cannot change after creation: an update with a different type fails with HTTP 400 |
name | string | Yes | Display name of the type |
schema | Record<string, unknown> | Yes | The JSON Schema every detail of the type must conform to |
description | string | No | Description of the type |
consentTemplate | string | No | The summary shown for a detail on the consent step |
reuse | boolean | No | Whether an earlier approval may stand in for the consent prompt |
processor | AuthorizationDetailProcessor | No | The 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.
| Function | Request | Returns |
|---|---|---|
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:
getFlowsandgetConnectionslist 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 filterouId eq "<id>". Each flow in the list carriesisOwnedByOU, which isfalsefor a flow shared with the unit.getConnectionsappliesouIdonly to the listing across every type.getFlowreturns the flow as the unit sees it. A flow shared with the unit comes back as itsvariablesonly. LeaveouIdout 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, withoutnodes, even withoutouId.
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.
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.
| Constant | Keys |
|---|---|
ApplicationQueryKeys | APPLICATIONS ('applications'), APPLICATION ('application') |
UserQueryKeys | USERS ('users'), USER ('user') |
AgentQueryKeys | AGENTS ('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:
| Code | Cause |
|---|---|
{function}-ValidationError-001 | url or baseUrl is not a valid URL. Thrown before any request is sent. |
{function}-ValidationError-002 | The resource identifier is empty. Thrown before any request is sent. |
{function}-ForbiddenError-001 | The server returned HTTP 403. The access token lacks permission for the operation. |
{function}-NotFoundError-001 | The server returned HTTP 404. The resource does not exist. |
{function}-ResponseError-001 | The server returned another non-2xx status. |
{function}-NetworkError-001 | The request failed before a response arrived, or the response could not be parsed. |
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.
}
}