oidc

The oidc domain has 10 actions. On the meta surface they are all reached through arcane_oidc; on the individual surface each one is its own tool; on the dynamic surface run them with arcane_execute_action and the canonical ID.

Summary

Action	Title	Kind
oidc.auth_url	Get OIDC auth URL	read
oidc.callback	Handle OIDC callback	write
oidc.config	Get OIDC config	read
oidc.device_auth_start	Initiate OIDC device authorization	write
oidc.device_token_exchange	Exchange device code for tokens	write
oidc.role_mapping_create	Create an OIDC role mapping	write
oidc.role_mapping_delete	Delete an OIDC role mapping	destructive
oidc.role_mapping_list	List OIDC group-to-role mappings	read
oidc.role_mapping_update	Update an OIDC role mapping	write
oidc.status	Get OIDC status	read

Actions

oidc.auth_url

Get OIDC auth URL

Generate an OIDC authorization URL for login

• Kind: read
• Required parameters: redirectUri
• Meta tool: arcane_oidc with "action": "auth_url"
• Individual tool: arcane_oidc_auth_url
• Arcane route: POST /api/oidc/url
• Operation ID: get-oidc-auth-url
• Usage: Requires OIDC to be enabled (settings oidcEnabled, oidcClientId, oidcIssuerUrl). The result carries the oidc_state cookie Arcane sets under cookies.oidc_state. Pass it to oidc.callback as oidcState.
• Related actions: oidc.callback, oidc.config, settings.update

oidc.callback

Handle OIDC callback

Process the OIDC callback and complete authentication

• Kind: write
• Required parameters: code, state
• Meta tool: arcane_oidc with "action": "callback"
• Individual tool: arcane_oidc_callback
• Arcane route: POST /api/oidc/callback
• Operation ID: handle-oidc-callback
• Usage: Completes a browser authorization-code login: pass the provider’s code and state plus the oidc_state cookie value from oidc.auth_url as oidcState. Rate-limited to 5 requests/min per client IP. Returns status authenticated with token, refreshToken and user, or status mfa_required with a passkey challenge. The user’s group-claim role mappings are re-applied on every login.
• Related actions: oidc.auth_url, oidc.role_mapping_list

oidc.config

Get OIDC config

Get the OIDC client configuration

• Kind: read
• Required parameters: none
• Meta tool: arcane_oidc with "action": "config"
• Individual tool: arcane_oidc_config
• Arcane route: GET /api/oidc/config
• Operation ID: get-oidc-config
• Usage: Public, no session needed. Returns the client-side OIDC settings (clientId, issuerUrl, redirectUri ending in /auth/oidc/callback, explicit endpoints, scopes, but never the secret). Fails with 400 ‘OIDC authentication is disabled’ when OIDC is off or neither client ID nor issuer URL is set. Use oidc.status for env-override info and settings.update to configure.
• Related actions: oidc.status, oidc.auth_url, settings.update

oidc.device_auth_start

Initiate OIDC device authorization

Start the device authorization flow for CLI authentication

• Kind: write
• Required parameters: none
• Meta tool: arcane_oidc with "action": "device_auth_start"
• Individual tool: arcane_oidc_device_auth_start
• Arcane route: POST /api/oidc/device/code
• Operation ID: initiate-oidc-device-auth
• Usage: Requires OIDC to be enabled. Starts the device flow at the provider’s device_authorization_endpoint (setting or discovery). Show the user userCode and verificationUri, then poll oidc.device_token_exchange with the returned deviceCode.
• Related actions: oidc.device_token_exchange, oidc.config

oidc.device_token_exchange

Exchange device code for tokens

Exchange a device code for authentication tokens

• Kind: write
• Required parameters: deviceCode
• Meta tool: arcane_oidc with "action": "device_token_exchange"
• Individual tool: arcane_oidc_device_token_exchange
• Arcane route: POST /api/oidc/device/token
• Operation ID: exchange-oidc-device-token
• Usage: Poll with deviceCode from oidc.device_auth_start until the user approves at the provider. Errors authorization_pending and slow_down (HTTP 400) mean retry later, expired_token means start again, access_denied and mfa_required (HTTP 403: passkey-MFA accounts cannot use the device flow, use an API key instead). On success returns token, refreshToken, expiresAt and user, and creates or updates the local user and its OIDC role assignments.
• Related actions: oidc.device_auth_start, api_key.my_create

oidc.role_mapping_create

Create an OIDC role mapping

• Kind: write
• Required parameters: claimValue, roleId
• Meta tool: arcane_oidc with "action": "role_mapping_create"
• Individual tool: arcane_oidc_role_mapping_create
• Arcane route: POST /api/oidc/role-mappings
• Operation ID: create-oidc-role-mapping
• Usage: Global admin only. Maps a value of the OIDC groups claim (setting oidcGroupsClaim, default groups) to roleId from role.list. Optional environmentId (from environment.list) scopes the grant, omit for global. Applied as source=‘oidc’ role assignments at each user’s next OIDC login, not retroactively.
• Related actions: oidc.role_mapping_list, oidc.role_mapping_update, role.list, environment.list

oidc.role_mapping_delete

Delete an OIDC role mapping

• Kind: destructive — requires confirm: true
• Required parameters: id
• Meta tool: arcane_oidc with "action": "role_mapping_delete"
• Individual tool: arcane_oidc_role_mapping_delete
• Arcane route: DELETE /api/oidc/role-mappings/{id}
• Operation ID: delete-oidc-role-mapping
• Usage: Global admin only. id from oidc.role_mapping_list. Rows with source env (declared by the OIDC_ROLE_MAPPINGS env var) are read-only and return 409. Role assignments users already received stay until their next OIDC login re-syncs them.
• Related actions: oidc.role_mapping_list, role.user_assignments_get

oidc.role_mapping_list

List OIDC group-to-role mappings

Returns every mapping. On each OIDC login the user’s group claim is matched against ClaimValue and matching rows become source=‘oidc’ role assignments.

• Kind: read
• Required parameters: none
• Meta tool: arcane_oidc with "action": "role_mapping_list"
• Individual tool: arcane_oidc_role_mapping_list
• Arcane route: GET /api/oidc/role-mappings
• Operation ID: list-oidc-role-mappings
• Usage: Global admin only. Each item holds id, claimValue, roleId, optional environmentId and source (manual = editable, env = from OIDC_ROLE_MAPPINGS, read-only). Use the id with oidc.role_mapping_update or oidc.role_mapping_delete.
• Related actions: oidc.role_mapping_create, oidc.role_mapping_update, oidc.role_mapping_delete, role.list

oidc.role_mapping_update

Update an OIDC role mapping

• Kind: write
• Required parameters: id, claimValue, roleId
• Meta tool: arcane_oidc with "action": "role_mapping_update"
• Individual tool: arcane_oidc_role_mapping_update
• Arcane route: PUT /api/oidc/role-mappings/{id}
• Operation ID: update-oidc-role-mapping
• Usage: Global admin only. id from oidc.role_mapping_list. Full replace: claimValue and roleId are required, and omitting environmentId makes the mapping global. Rows with source env return 409. Takes effect at each user’s next OIDC login.
• Related actions: oidc.role_mapping_list, role.list, environment.list

oidc.status

Get OIDC status

Get the current OIDC configuration status

• Kind: read
• Required parameters: none
• Meta tool: arcane_oidc with "action": "status"
• Individual tool: arcane_oidc_status
• Arcane route: GET /api/oidc/status
• Operation ID: get-oidc-status
• Usage: Public, no session needed. Returns envForced (oidcEnabled pinned by environment variable), envConfigured (env client ID and issuer set, only computed when envForced), mergeAccounts, providerName and providerLogoUrl. It does not say whether OIDC is enabled in settings. Read oidcEnabled via settings.get or try oidc.config.
• Related actions: oidc.config, settings.get