Import Resources
ThunderID provides the POST /import API to import declarative YAML content into runtime stores.
Declarative resource attributes use camelCase (for example ouId, authFlowId, clientId), matching the REST API.
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:
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:
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:
| Resource | Code | Resource | Code |
|---|---|---|---|
| Agent | AGT-1063 | Notification template | NTM-1032 |
| Application | APP-1069 | Organization unit | OU-1026 |
| Authorization detail type | RAR-1030 | Project | PRJ-1014 |
| Connection | CON-1040 | Resource server | RES-1028 |
| Credential configuration | VCI-2016 | Role, role assignee | ROL-1043, ROL-1044 |
| Flow | FLM-1048 | Server configuration | SCF-1006 |
| Group, group member | GRP-1023, GRP-1024 | Theme | THM-1020 |
| Language (translations) | I18N-1009 | User | USR-1044 |
| Layout | LAY-1021 | User type, agent type | USRS-1023 |
| Presentation definition | VP-2021 | SCIM (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-1024orROL-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: truefor 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:
{
"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.
- Omitted: defaults to
options.continueOnError:- Omitted: defaults to
true. true: continues processing remaining documents after an item failure.false: stops at the first failed item.
- Omitted: defaults to
options.target:- Omitted: defaults to
runtime. runtimeis currently supported.
- Omitted: defaults to
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.
- Omitted: defaults to
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.
{
"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 absentand does not add tosummary.deleted. - A type with no runtime delete is reported, not skipped.
server_configis 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_typedeletion fails withUSRS-1022while 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 withAGT-1054because their new type does not exist, and the removal withUSRS-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'typeto 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 withAGT-1027, an application withAPP-1030, and a flow withFLM-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.
deletionsalone 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.
{
"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.
{
"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.
{
"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
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.
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 type | Handle field | Resolves to |
|---|---|---|
| Application | ouHandle | ouId |
| Application | authFlowHandle | authFlowId |
| Application | registrationFlowHandle | registrationFlowId |
| Application | recoveryFlowHandle | recoveryFlowId |
| Agent | authFlowHandle | authFlowId |
| Agent | registrationFlowHandle | registrationFlowId |
| User type | ouHandle | ouId |
| Flow | ouHandle | ouId |
| Connection | ouHandle | ouId |
| Notification template | ouHandle | ouId |
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
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 kind | Error code |
|---|---|
| Identity provider | IDP-1016 |
| SMS or email provider | MNS-1020 |
| AuthZEN PDP | CON-1025 |
| HTTP endpoint | CON-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.
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.
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
ouIdorouHandle. 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.
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
ouIdorouHandle. 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
declarativeorcompositemode. A file loaded at startup does not applyvariableValues, 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.
| Field | Required | Description |
|---|---|---|
channel | Yes | The delivery channel. One of email or sms. |
handle | Yes | Stable identifier, unique within the channel. Lowercase alphanumeric with dashes or underscores (kebab or snake case). Immutable after creation. |
displayName | Yes | Human-readable name. |
description | No | Optional description. |
content.subject | Email only | Subject line. Required for email, not allowed for sms. |
content.body | Yes | Message body. |
design.colorScheme | Email only | Optional color scheme, light or dark. Not allowed for sms. |
Channel rules are enforced on both apply and dry-run:
emailrequirescontent.subject, and may setdesign.smsmust not setcontent.subjectordesign.
Example: Email Template
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
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.
| Handle | Channels | Purpose |
|---|---|---|
user-invite | email, sms | Invite a new user to complete their registration. |
self-registration | email, sms | Complete a self-service registration. |
magic-link | Sign in through a secure link. | |
password-recovery | Reset an account password. | |
ciba-notification | email, sms | Approve a backchannel (CIBA) authentication request. |
otp | email, sms | Verify an email address or phone number with a one-time passcode. |
self-email-verification | Verify a signed-in user's own email address from a link. | |
admin-initiated-email-verification | Verify 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
delimiteris optional and defaults toresource.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
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.
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.
{
"resourceType": "application",
"resourceKey": "my-console-app"
}
Example response:
{
"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).