Skip to main content

Import Resources

ThunderID provides the POST /import API to import declarative YAML content into runtime stores.

note

Declarative resource attributes use camelCase (for example ouId, authFlowId, clientId), matching the REST API.

note

An application resource requires a type attribute (browser, fullstack, mobile, m2m, or custom). The type is set on creation and does not change on a later import. See Application Types.

Use this API when you want to:

  • Bootstrap resources from a YAML bundle.
  • Apply declarative updates in CI/CD.
  • Test resource definitions before applying them.

Authentication and authorization​

Use an access token with the system scope.

Send the token in the Authorization header:

http
Authorization: Bearer <access_token>

Resources Imported Only With the Management API Key​

On a data plane, including the all-in-one server, no token writes the following resources, whatever its scopes:

  • Root organization units
  • Themes and layouts
  • Translations
  • Server configuration
  • Authorization details types

Import them with the management API key instead. A token can still read them, and a control plane token with the matching scope still writes them. When a token imports one of them, the import reports that item as failed with the code SSE-4030.

The key is off by default. To turn it on, set server.security.management_api_key_hash to the SHA-256 digest of the key, then send the key in the API-Key header:

http
API-Key: <management_api_key>

The key opens the import APIs (/import, /import/managed and /import/delete), the variable store (/variables) and the secret store (/secrets), and nothing else. Only the managed import marks what it writes as read only.

Managed Import​

POST /import/managed takes the same request and returns the same response as POST /import. It exists on a data plane only: a control plane does not serve it, and neither does a data plane on an older release, which answers 404. A control plane that gets that 404 deploys through the plain POST /import instead, so what it writes is editable on that data plane (see Apply a Version). It is the import a control plane uses to deploy to a data plane. Only the management API key may call it. A token is refused with IMP-1008.

Everything a managed import writes is read only on the data plane. The data plane's own APIs, and so its console, refuse to update or delete it, and refuse changes to what it holds, such as the resources and actions of a resource server. Only a later managed import changes or removes it. A plain POST /import is refused the same way for a resource a managed import wrote. Each refusal has an error code of its own for the type of resource, for example GRP-1023 for a group and AGT-1063 for an agent.

The refusal answers 403 on update and delete, and on the other writes to the resource, and carries the code of the resource's type:

ResourceCodeResourceCode
AgentAGT-1063Notification templateNTM-1032
ApplicationAPP-1069Organization unitOU-1026
Authorization detail typeRAR-1030ProjectPRJ-1014
ConnectionCON-1040Resource serverRES-1028
Credential configurationVCI-2016Role, role assigneeROL-1043, ROL-1044
FlowFLM-1048Server configurationSCF-1006
Group, group memberGRP-1023, GRP-1024ThemeTHM-1020
Language (translations)I18N-1009UserUSR-1044
LayoutLAY-1021User type, agent typeUSRS-1023
Presentation definitionVP-2021SCIM (any of the above)SCIM-1042

A managed import that finds a flow with the same handle that no control plane deployed does not take it over. It reports that item as failed with IMP-1009, because the control plane could not later remove a resource it does not know by its own ID. Rename or remove the flow on the data plane first.

A deployed user is read only the same way, which includes setting a password through the data plane's credential APIs and recovery flows. A deployed user cannot change their own password on the data plane until a later deploy changes it.

What a plain import, or a call to the data plane's own APIs, creates stays editable.

  • Group members and role assignments are owned one by one. A managed import removes the members of a group, and the assignees of a role, that an earlier managed import deployed and no longer sends. Members and assignees added on the data plane stay, even on a group or role that was deployed. Removing a member or assignee that a managed import deployed through the API is refused with GRP-1024 or ROL-1044.
  • Server configuration and translations. The API refuses to write a server configuration section, or a translation language, that a managed import deployed. The server's own updates, such as the localized names of an application, still go through.
  • Reads show it. Lists and reads return isReadOnly: true for what was deployed. Application and agent details, connections, projects, credential and presentation configurations, translations and server configuration sections do not carry the field in their responses yet. The writes to them are refused all the same.

A managed import marks a resource only after it writes it successfully, and not on a dry run. When it cannot mark one, it reports that item as failed.

Endpoint Summary​

  • POST /import: Imports one or more YAML documents into runtime stores.
  • POST /import/managed: Imports the same documents as a control plane deploys them, which makes them read only on the data plane. Management API key only.
  • POST /import/delete: Deletes a file-backed declarative resource file by type and key.

Request Model​

POST /import accepts the following payload:

json
{
"content": "# YAML content with one or more documents",
"variables": {
"CLIENT_ID": "my-client-id"
},
"dryRun": false,
"deletions": [
{
"resourceType": "application",
"id": "550e8400-e29b-41d4-a716-446655440000"
}
],
"options": {
"upsert": true,
"continueOnError": true,
"target": "runtime"
}
}

A request has to carry work to do: content to upsert, deletions to remove, or both. A request carrying neither is rejected.

Options Behavior​

  • options.upsert:
    • Omitted: defaults to true.
    • true: updates existing resources when supported.
    • false: skips update behavior and attempts create semantics.
  • options.continueOnError:
    • Omitted: defaults to true.
    • true: continues processing remaining documents after an item failure.
    • false: stops at the first failed item.
  • options.target:
    • Omitted: defaults to runtime.
    • runtime is currently supported.
  • options.forceSharingEdits:
    • Omitted: defaults to false, and a change the sharing policies API refuses, such as a different reach, fails the document.
    • true: the policy is rewritten in place instead, and the reshares that lose their standing are removed.

Removing Resources​

content can create and update but never remove, so a resource dropped from a configuration would otherwise linger on every deployment that configuration was applied to. deletions names the resources to remove, so one request can reconcile a deployment with the configuration as it now stands.

Each entry names a resourceType and an id. User types and agent types are separate resource types, user_type and agent_type, as they are in content. A translation is identified by its language, such as fr-FR, and removing it clears every custom translation of that language.

json
{
"deletions": [
{ "resourceType": "application", "id": "550e8400-e29b-41d4-a716-446655440000" },
{ "resourceType": "agent_type", "id": "660e8400-e29b-41d4-a716-446655440001" }
]
}

Deletion Behavior​

  • Removals run after the upserts. A resource this same request moved or replaced is in place before its predecessor is pruned.
  • Removals are ordered as the reverse of the import dependency order, so a dependent goes before what it depends on rather than failing on a reference that is still live.
  • Removing something already absent is a success. Re-applying the same configuration has to be a no-op, and a request that failed because the removal already happened would make retrying impossible. Where the service reports not found, the outcome carries the message resource already absent and does not add to summary.deleted.
  • A type with no runtime delete is reported, not skipped. server_config is reported as an unsupported outcome, because a configuration that dropped it would otherwise look reconciled when it is not. To clear a section, import it with an empty value instead.
  • A removal the owning service refuses is reported with its reason. An agent_type deletion fails with USRS-1022 while any agent is of that agent type, or while an application, agent, or flow lists it in its allowed agent types.
  • Replace an agent type within one organization unit in two requests. An organization unit can have only one agent type, and an agent type cannot be removed while it is in use. So a request that adds the new agent type, moves the agents to it, and removes the old one fails the same way however often it is sent: the new agent type with USRS-1021, the agents with AGT-1054 because their new type does not exist, and the removal with USRS-1022. In a first request, move the old agent type to an organization unit that has no agent type. In a second, add the new agent type, change the agents' type to it, put the new handle in place of the old one wherever an application, agent, or flow lists it in its allowed agent types, and remove the old agent type.
  • The two requests work only for resources held in the database. That covers the agent types and every agent, application, and flow the second request changes. An import cannot change one that a resource file defines: the agent type fails with USRS-1008, an agent with AGT-1027, an application with APP-1030, and a flow with FLM-1017. The server also checks each agent loaded from a file against its agent type's organization unit when it starts, so moving an agent type away from such agents makes the next start fail. Change those resources in their resource files instead.
  • A dry run reports what it would remove and removes nothing.
  • deletions alone is a valid request. Removing what a configuration dropped does not require also restating what it kept.

Deletions follow options.continueOnError as documents do: by default one refused removal does not hold back the rest.

Removing Role Assignees and Group Members​

A role document's assignments and a group document's members are added on import, but an assignee or member the document leaves out is not taken off. To take one off while the role or group stays, name it in a role_assignment or group_member entry. id is the role or group, and members lists who to take off, each by id and type. A role assignment also gives the organization unit it was made in as ouId, which is required.

json
{
"deletions": [
{
"resourceType": "role_assignment",
"id": "770e8400-e29b-41d4-a716-446655440002",
"members": [{ "id": "880e8400-e29b-41d4-a716-446655440003", "type": "user", "ouId": "990e8400-e29b-41d4-a716-446655440004" }]
},
{
"resourceType": "group_member",
"id": "aa0e8400-e29b-41d4-a716-446655440005",
"members": [{ "id": "880e8400-e29b-41d4-a716-446655440003", "type": "user" }]
}
]
}

These run before any resource is removed, so an assignee removed in the same request is still there to be named. Each goes through the role or group service as a removal through its API does. Someone who no longer holds the role directly in that unit, or is no longer in the group, is already off it and is skipped: for example a user deleted since, or a unit the role is no longer shared with. A role or group that is already gone is reported as resource already absent. Each entry gets one outcome, with the role or group id as resourceId. Everyone an entry names is checked before anyone is taken off, so when one is refused, the entry fails and the role or group is left as it was.

Removing Sharing Policies​

A policy left out of a document is not removed. To remove one, name it in sharingRemovals, with the resource type, the resource id, and the organization unit that issued it (omit it for the owner). Each removal runs once its resource is written, or just before it for a flow, and the reshares that lose their standing go with it. The result for the resource lists them in removedSharing. If a removal fails, the resource's result fails. The response carries sharingRemovalsAccepted: true when the deployment acts on sharingRemovals, and an older deployment omits it, which lets the sender tell its removals were ignored.

json
{
"content": "...",
"sharingRemovals": [
{ "resourceType": "flow", "id": "550e8400-e29b-41d4-a716-446655440000" },
{
"resourceType": "flow",
"id": "550e8400-e29b-41d4-a716-446655440000",
"initiatingOuId": "7f3c1d52-8a4e-4b6a-9c21-0d5e6f7a8b90"
}
],
"options": { "forceSharingEdits": true }
}

The first entry removes the owner's policy, since it has no initiatingOuId. The second removes the policy that organization unit issued.

Response Model​

A successful import returns summary metrics and per-document outcomes.

json
{
"summary": {
"totalDocuments": 2,
"imported": 2,
"deleted": 1,
"failed": 0,
"importedAt": "2026-04-23T12:10:52Z"
},
"results": [
{
"resourceType": "connection",
"resourceId": "550e8400-e29b-41d4-a716-446655440000",
"resourceName": "Google",
"operation": "create",
"status": "success"
},
{
"resourceType": "flow",
"resourceId": "660e8400-e29b-41d4-a716-446655440001",
"resourceName": "Default Login Flow",
"operation": "update",
"status": "success"
},
{
"resourceType": "application",
"resourceId": "550e8400-e29b-41d4-a716-446655440000",
"operation": "delete",
"status": "success"
}
]
}

summary.deleted counts the deletions this request completed, separately from imported. A dry run completes none, and a resource a service reports as not found is not counted, though both are still reported as a success in results. Not every service distinguishes an absent id from a removed one, so treat this as the number of deletions that completed rather than a guarantee that each one had something to remove. Every deletion appears in results with operation set to delete, and that list is where the per-resource outcome is.

Example: Import with Variables​

bash
curl -X POST "https://localhost:8090/import" \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"content": "resource_type: application\nname: Console\ntype: browser\nauthFlowId: {{.AUTH_FLOW_ID}}\n",
"variables": {
"AUTH_FLOW_ID": "edc013d0-e893-4dc0-990c-3e1d203e005b"
},
"dryRun": false,
"options": {
"upsert": true,
"continueOnError": true,
"target": "runtime"
}
}'

Agent Resources​

An agent resource stores its name in attributes.name. The agent type schema controls validation; the default type requires a unique string value for name.

yaml
resource_type: agent
id: 01900000-0000-7000-8000-000000000050
type: default
ouId: "<organization-unit-id>"
owner:
id: "<owner-user-id>"
attributes:
name: Calendar Agent
modelProvider: anthropic

Replace the organization unit and owner placeholders with existing IDs. This example creates an agent record without an OAuth profile. Include inboundAuthConfig when the agent needs OAuth credentials. See Create and Manage Agents.

The Console import summary resolves each agent's label using the agent type's systemAttributes.display setting, which selects name by default. It checks agent types in the import bundle first, then types on the server. If no display value is available, it shows the agent ID. An import document with neither a display value nor an ID shows an unnamed-agent label.

The resolved label is not a separate name or display field in the resource. Store attribute values under attributes; configure the display mapping on the agent type. See Agent Schema.

Cross-Resource References by Handle​

Instead of embedding environment-specific resource identifiers in YAML files, you can reference organization units and flows by their human-readable handles. The importer resolves each handle to its resource identifier at import time, making the same YAML portable across environments.

The following handle fields are supported:

Resource typeHandle fieldResolves to
ApplicationouHandleouId
ApplicationauthFlowHandleauthFlowId
ApplicationregistrationFlowHandleregistrationFlowId
ApplicationrecoveryFlowHandlerecoveryFlowId
AgentauthFlowHandleauthFlowId
AgentregistrationFlowHandleregistrationFlowId
User typeouHandleouId
FlowouHandleouId
ConnectionouHandleouId
Notification templateouHandleouId

If you provide both a handle field and the corresponding ID field, the ID takes precedence and the handle is ignored.

A flow document must carry ouId or ouHandle, because every flow belongs to exactly one organization unit. A document with neither fails to import, and a dry run reports the same failure. The same rule applies to flow files loaded at startup: the server fails to load a file with no owner. For the details, see Organization Unit Ownership.

Updating an existing application or agent with a document that sets only a handle field re-resolves it and keeps the resolved ID.

If a handle cannot be resolved (because the target resource does not exist or the required adapter is not configured), the import item fails with a descriptive error message. When continueOnError is true, the importer continues processing the remaining documents.

Example: Application with Handle References​

yaml
resource_type: application
name: My App
type: fullstack
ouHandle: default
authFlowHandle: default-basic-flow
registrationFlowHandle: default-registration-flow
isRegistrationFlowEnabled: true

Connections and Organization Units​

A connection document for an identity provider, an SMS or email provider, an AuthZEN PDP connection, or an HTTP endpoint connection must carry ouId or ouHandle, because every connection belongs to exactly one organization unit. A document with neither fails to import, and a dry run reports the same failure. The same rule applies to connection files loaded at startup: the server fails to load a file with no owner. The error code of a missing owner depends on the kind of connection:

Connection kindError code
Identity providerIDP-1016
SMS or email providerMNS-1020
AuthZEN PDPCON-1025
HTTP endpointCON-1030

When a connection document has both ouId and ouHandle, ouId wins. ThunderID logs a warning and does not check that the two name the same organization unit. An export writes ouId for each connection, not ouHandle.

yaml
resource_type: connection
id: 0193b0a1-1003-7000-8000-000000000001
name: Corp OIDC
ouHandle: default
type: oidc
clientId: "{{.CORP_OIDC_CLIENT_ID}}"
clientSecret: "{{.CORP_OIDC_CLIENT_SECRET}}"
redirectUri: "{{.CORP_OIDC_REDIRECT_URI}}"
authorizationEndpoint: https://idp.example.com/oauth2/authorize
tokenEndpoint: https://idp.example.com/oauth2/token

Sharing Policies on Connections​

A connection document of any kind can carry a sharingPolicies list that shares the connection with other organization units. Each entry has the same fields as a sharing policy on any other resource. A shared connection stays in its owner's organization unit, and the organization units it reaches can use it but cannot override any of its settings.

yaml
resource_type: connection
id: 0193b0a1-1003-7000-8000-000000000002
name: Corp SMTP
ouHandle: default
type: email-smtp
host: smtp.example.com
port: 587
fromAddress: noreply@example.com
sharingPolicies:
- childUnits:
mode: all

The importer handles the policies of a document as follows:

  • It writes the connection first and then records the policies against the organization unit that owns the connection, whether the document names that unit with ouId or ouHandle. A policy the connection already has from that organization unit is updated, and a policy that the document does not name is kept.
  • If ThunderID refuses a policy, the item fails. When the import created the connection, it removes the connection so that a retry is not blocked by a connection that is left behind. An update that fails on a policy keeps the changes it made to the connection.
  • A dry run validates the connection and records no policy.
  • An export writes the sharing policies of each connection into its document, so importing the export recreates the same sharing.
  • Connection files loaded at startup declare their policies the same way.

Sharing Policies on Flows​

A flow document can carry a sharingPolicies list that shares the flow with other organization units. Each entry has the same fields as a sharing policy on any other resource. A flow document must name its owner with ouId or ouHandle. A shared flow stays in its owner's organization unit. The organization units it reaches cannot change its definition, but they can set the values of the variables the owner opens to them.

The overlay rules of a flow policy govern variables. The key of a rule is variables. followed by the identifier of a variable that the flow declares on a VARIABLES node. Each rule takes the fields editable, value, allowedValues, and excludedValues, as described in Overlay Rules. A variable holds one value, so value lists at most one entry.

yaml
resource_type: flow
id: 0193b0a1-1001-7000-8000-000000000042
handle: acme-login
name: Acme Login Flow
flowType: AUTHENTICATION
ouHandle: default
nodes:
- id: start
type: START
onSuccess: resolve_ou
- id: resolve_ou
type: TASK_EXECUTION
executor:
name: OUResolverExecutor
properties:
resolveFrom: prompt
parentOuId: 0193b0a1-2001-7000-8000-000000000001
onSuccess: resolve_variables
- id: resolve_variables
type: VARIABLES
inputs:
- identifier: supportEmail
type: EMAIL_INPUT
label: Support email
defaultValue: support@example.com
- identifier: mfaMode
type: SELECT
label: Second factor
options:
- NONE
- SMS_OTP
- EMAIL_OTP
defaultValue: NONE
onSuccess: end
- id: end
type: END
sharingPolicies:
- childUnits:
mode: all
overlayRules:
variables.supportEmail:
editable: true
variables.mfaMode:
editable: true
allowedValues:
- NONE
- SMS_OTP
variableValues:
- ouId: 0193b0a1-2001-7000-8000-000000000007
values:
supportEmail: help@acme-emea.example
mfaMode: SMS_OTP

A document can also carry variableValues, the values that the organization units the flow is shared with saved for its variables. Each entry names a unit with ouId and gives the values by variable identifier, as PUT /flows/{flowId}/variables takes them. An export writes them, so a flow keeps its overrides when you import it into another deployment, such as a data plane that a control plane applies versions to.

The importer handles the policies and values of a document as follows:

  • When the import creates the flow, it writes the flow first and then records the policies against the organization unit that owns the flow, whether the document names that unit with ouId or ouHandle. If ThunderID refuses a policy, the item fails and the import removes the flow, so that a retry is not blocked by a flow that is left behind.
  • When the import updates a flow, it writes the new definition and the policies in one transaction. If ThunderID refuses the document, the flow keeps its previous definition and policies. A policy the flow already has from that organization unit is updated, and a policy that the document does not name is kept.
  • It checks the terms of each policy against the variables the new definition declares. A rule must name a declared variable, and every value in it must be valid for the type and constraints of that variable. A value that names a connection must name an existing connection of a kind the variable takes.
  • On an update that carries sharingPolicies, it does not check the new definition against the policies and saved values the flow held before. It checks the policies that remain after the replace, so a document whose definition and policies agree is accepted. For example, you can remove a variable, or an option of a variable, and the matching terms of its policy in the same document.
  • After the policies, it sets the values of each unit in variableValues, checked as they would be if the unit set them through the API. A unit may set only what its rules let it, and a connection must be one the unit can see. A unit the document does not name keeps its own values. If ThunderID refuses a value, the item fails. When the import created the flow, it removes the flow. When the import updated the flow, the new definition and policies stay.
  • A dry run validates the flow and records no policy or value.
  • An export writes the sharing policies and the saved values of each flow into its document, so importing the export recreates the same sharing and the same overrides.
  • Flow files loaded at startup declare their policies the same way. ThunderID loads them when it loads flows from files, which is when the flow store is in the declarative or composite mode. A file loaded at startup does not apply variableValues, so import the document to set the values.

Mandated Roles on User Shares​

A user document can carry a sharingPolicies list whose entries mandate roles with a roles overlay rule. See Mandate Roles on a Shared User. An import replays those shares after the roles, so one document can carry a user, the role, and the share that mandates it. A role export leaves mandated assignments out, because the share recreates them on import.

When and how the shares are replayed depends on whether the user already exists:

  • For a new user, the import replays every share with the user, leaving the roles rules out, and replays the shares that carry roles in full after the roles. The user therefore reaches its organization units before a role later in the document is assigned to it there.
  • For an existing user, once any of its shares carries roles, the import replays all of its shares after the roles. A role document in the same import that assigns the user directly in an organization unit the import newly shares the user into then fails, because the user does not reach that unit yet. Import the user first, then the roles.

Because roles are imported before the shares, one import cannot both drop a role from a share's mandate and stop sharing that role with the organization unit. The role document is refused with ROL-1037 while the mandate still stands. Import the user's share first, then the role.

Dry-Run Behavior​

When dryRun is true, the importer validates documents and reports what would be created or updated, but does not write any changes to runtime stores. Handle resolution is mostly skipped in dry-run mode: the importer accepts handle fields, such as the flow handles of an application, without attempting to look up their target resources. The exception is ouHandle, which is resolved for every resource type that has one, so a handle that does not match an organization unit fails the dry run as it would a real import. Use dry-run to validate YAML structure before applying it.

Notification Templates​

A notification_template document defines a channel-specific message template. Templates are keyed by (channel, handle): the handle is unique within a channel and is immutable after creation. With upsert enabled, an existing template with the same handle is updated; otherwise a duplicate handle fails with a conflict.

FieldRequiredDescription
channelYesThe delivery channel. One of email or sms.
handleYesStable identifier, unique within the channel. Lowercase alphanumeric with dashes or underscores (kebab or snake case). Immutable after creation.
displayNameYesHuman-readable name.
descriptionNoOptional description.
content.subjectEmail onlySubject line. Required for email, not allowed for sms.
content.bodyYesMessage body.
design.colorSchemeEmail onlyOptional color scheme, light or dark. Not allowed for sms.

Channel rules are enforced on both apply and dry-run:

  • email requires content.subject, and may set design.
  • sms must not set content.subject or design.

Example: Email Template​

yaml
resource_type: notification_template
channel: email
handle: user-invite
ouHandle: default
displayName: User Invitation Email
description: Sent when a user is invited.
content:
subject: You are invited
body: "<p>{{ctx(inviteLink)}}</p>"
design:
colorScheme: light

Example: SMS Template​

yaml
resource_type: notification_template
channel: sms
handle: otp-verification
ouHandle: default
displayName: OTP Verification SMS
content:
body: "Your verification code is {{ctx(otpCode)}}"

Default Templates​

ThunderID ships a default bundle of notification templates. Importing your own document with the same (channel, handle) and upsert enabled replaces the default.

HandleChannelsPurpose
user-inviteemail, smsInvite a new user to complete their registration.
self-registrationemail, smsComplete a self-service registration.
magic-linkemailSign in through a secure link.
password-recoveryemailReset an account password.
ciba-notificationemail, smsApprove a backchannel (CIBA) authentication request.
otpemail, smsVerify an email address or phone number with a one-time passcode.
self-email-verificationemailVerify a signed-in user's own email address from a link.
admin-initiated-email-verificationemailVerify an email address from a link an administrator asked for.

Resource Servers​

A resource_server document declares a resource server with its resources and actions. List the actions of the resource server itself under the top-level actions field, and the actions of a resource under that resource's actions field. A resource's permission joins the handles from the top-level resource down to that resource with the resource server's delimiter. A resource action's permission appends the action handle to the resource's permission. A resource server action's permission is the action handle alone, such as audit.

Delimiter and Handles​

  • delimiter is optional and defaults to resource.default_delimiter. It must be one of ., _, :, -, or /.
  • A handle can contain letters, digits, ., _, :, -, and /, up to 100 characters, but not the resource server's delimiter.

Parent References​

A handle must be unique under its parent. Set parent to the full path of the parent resource, such as parent: app:team:member.

Example​

yaml
resource_type: resource_server
id: 01900000-0000-7000-8000-0000000009ff
name: Team Workspace
identifier: "urn:example:workspace"
ouHandle: default
delimiter: ":"
actions:
- { name: Audit, handle: audit }
resources:
- { name: App, handle: app }
- { name: Project, handle: project, parent: app }
- name: Project Member
handle: member
parent: "app:project"
actions:
- { name: Read, handle: read }
- { name: Team, handle: team, parent: app }
- name: Team Member
handle: member
parent: "app:team"
actions:
- { name: Read, handle: read }
- { name: Lead, handle: lead, parent: "app:team:member" }

Upserting and Removing Resource Servers​

A resource_server document describes the whole resource server, so an upsert makes the stored resources and actions match it. Resources and actions that the document no longer lists are deleted, matched by their permission. A document that lists no resources or actions removes all of the server's resources and actions. Resources and actions that the document lists are created if absent and left as they are otherwise.

A deletions entry of type resource_server removes the resource server's actions, then its resources, deepest first, then the resource server. This differs from DELETE /resource-servers/{id}, which still refuses with RES-1006 while the resource server has resources or actions.

These removals run one at a time, not in a single transaction. If one fails, the resource server can be left with some of its children removed. Send the same request again to finish the removal.

Authorization Detail Types​

An authorization_detail_type document declares an intent, an RFC 9396 authorization details type that clients request through the authorization_details parameter. It takes the same fields as the management API: id, type, name, description, schema, consentTemplate, processor, and reuse. The import validates it as the API does and keeps its id, so an intent keeps the same ID across deployments.

schema can be a YAML mapping, as below, or the schema's JSON, which is how an export writes it. Either way, the properties keep their order, which is the order of the rows on the consent card.

yaml
resource_type: authorization_detail_type
id: 0193b0a1-5001-7000-8000-000000000001
type: fx_transfer
name: Foreign exchange transfer
description: Transfer money to an account in another currency
schema:
type: object
properties:
amount:
type: number
title: Amount
minimum: 1
multipleOf: 0.01
policy:
modification: decrease
modifiableBy: [user]
currency:
type: string
title: Currency
enum: [EUR, GBP, USD]
rate:
type: number
title: Exchange rate
policy:
suppliedBy: processor
required: [amount, currency, rate]
consentTemplate: "Transfer {{amount}} {{currency}}"
processor:
endpoint: https://fx.example.com/rar/process
authentication:
type: bearer
properties:
token: "{{.FX_PROCESSOR_TOKEN}}"
reuse: false

{{amount}} and {{currency}} in consentTemplate are summary placeholders and are kept as written. {{.FX_PROCESSOR_TOKEN}} is a template variable, resolved from variables on import.

An intent imported through POST /import is stored like one created through the API. On a data plane, import intents with the management API key, and change them later with another import: an import with a system token reports the intent as failed with SSE-4030. An intent written by POST /import/managed is read only, and a plain import that changes or deletes it fails with RAR-1030. A processor credential can also be a sec: value reference. To declare read-only intents instead, place one document per file in config/resources/authorization_detail_types/. ThunderID loads these files at startup when authorization_detail_type.store is declarative or composite, the default. In a file, the processor credential can refer to an environment variable with the same {{.NAME}} syntax, read when the server starts. The API returns a file-based intent with isReadOnly: true and refuses to change it with RAR-1013, and so does an import of a document with the same id. See Declarative Intents.

Delete File-Backed Declarative Resource​

POST /import/delete removes a declarative file-backed resource by resourceType and resourceKey.

json
{
"resourceType": "application",
"resourceKey": "my-console-app"
}

Example response:

json
{
"resourceType": "application",
"resourceKey": "my-console-app",
"deletedFile": "applications/my-console-app.yaml"
}

Expected Side Effects​

When import runs with dryRun=false, ThunderID persists resource changes in runtime stores.

When POST /import/delete succeeds, ThunderID removes the matching declarative YAML file from config/resources.

Error Handling​

Typical failures include:

  • Invalid request payload (IMP-1001).
  • Invalid YAML content (IMP-1002).
  • Template resolution failures (IMP-1003).
  • Adapter not configured for a resource type (IMP-1004).
  • Internal server error (SSE-5000).

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.