SutraID|Developer Docs
QuickstartAPI ReferenceDashboard

OIDC Configuration

Manage OIDC configuration for applications including custom scopes, token claims, claim transformation regex rules, signing keys, and token lifetime policies.

GET/api/v1/applications/:appId/oidc-configGet OIDC ConfigBearer Token▾

Returns the complete OIDC configuration for an application, including scopes, claims, regex rules, signing keys, and token policy.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
idstringOptionalOIDC configuration ID.e.g. oidc_cfg_01hxyz
applicationIdstringOptionalThe associated application ID.e.g. app_01hxyz
scopesobject[]OptionalList of configured OAuth scopes.
claimsobject[]OptionalList of configured token claims.
regexRulesobject[]OptionalList of claim transformation regex rules.
signingKeysobject[]OptionalList of token signing keys.
tokenPolicyobjectOptionalToken lifetime and rotation policy settings.
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z
updatedAtstringOptionalISO 8601 last-updated timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "id": "oidc_cfg_01hxyz",
  "applicationId": "app_01hxyz",
  "scopes": [
    {
      "id": "scope_01hxyz",
      "name": "openid",
      "description": "OpenID Connect scope",
      "isDefault": true
    },
    {
      "id": "scope_02hxyz",
      "name": "profile",
      "description": "User profile information",
      "isDefault": true
    },
    {
      "id": "scope_03hxyz",
      "name": "custom:billing",
      "description": "Access billing information",
      "isDefault": false
    }
  ],
  "claims": [
    {
      "id": "claim_01hxyz",
      "name": "department",
      "userAttribute": "department",
      "regexRuleId": null,
      "targetTokens": [
        "ID_TOKEN"
      ]
    }
  ],
  "regexRules": [
    {
      "id": "rule_01hxyz",
      "name": "Extract domain",
      "pattern": "^.+@(.+)$",
      "replacement": "$1",
      "flags": "i"
    }
  ],
  "signingKeys": [
    {
      "id": "key_01hxyz",
      "kid": "sig-rs256-2025",
      "algorithm": "RS256",
      "isDefault": true,
      "createdAt": "2025-01-15T10:30:00Z"
    }
  ],
  "tokenPolicy": {
    "accessTokenLifetime": 3600,
    "idTokenLifetime": 3600,
    "refreshTokenLifetime": 86400,
    "rotationEnabled": true,
    "reuseInterval": 0
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config" \
  -H "Authorization: Bearer <token>"
POST/api/v1/applications/:appId/oidc-config/scopesCreate Custom ScopeBearer Token▾

Add a custom OAuth scope to the application OIDC configuration. Custom scopes can be used to control access granularity beyond the standard OpenID Connect scopes.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Request Body

NameTypeRequiredDescription
namestringRequiredThe scope name (e.g. "custom:billing"). Must be unique within the application.e.g. custom:billing
descriptionstringOptionalA human-readable description of what the scope grants access to.e.g. Access billing information and invoices.
isDefaultbooleanOptionalWhether this scope is included by default when no scopes are explicitly requested.e.g. false

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique scope ID.e.g. scope_01hxyz
namestringOptionalScope name.e.g. custom:billing
descriptionstringOptionalScope description.e.g. Access billing information and invoices.
isDefaultbooleanOptionalWhether the scope is a default scope.e.g. false
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "id": "scope_01hxyz",
  "name": "custom:billing",
  "description": "Access billing information and invoices.",
  "isDefault": false,
  "createdAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/scopes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "custom:billing",
    "description": "Access billing information and invoices.",
    "isDefault": false
  }'
GET/api/v1/applications/:appId/oidc-config/scopesList ScopesBearer Token▾

List all configured OAuth scopes for the application, including both default and custom scopes.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
[]object[]OptionalArray of scope objects.
[].idstringOptionalUnique scope ID.e.g. scope_01hxyz
[].namestringOptionalScope name.e.g. openid
[].descriptionstringOptionalScope description.e.g. OpenID Connect scope
[].isDefaultbooleanOptionalWhether the scope is a default scope.e.g. true
[].createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "data": [
    {
      "id": "scope_01hxyz",
      "name": "openid",
      "description": "OpenID Connect scope",
      "isDefault": true,
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "scope_02hxyz",
      "name": "profile",
      "description": "User profile information",
      "isDefault": true,
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "scope_03hxyz",
      "name": "custom:billing",
      "description": "Access billing information and invoices.",
      "isDefault": false,
      "createdAt": "2025-01-16T08:00:00Z"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/scopes" \
  -H "Authorization: Bearer <token>"
POST/api/v1/applications/:appId/oidc-config/claimsCreate Custom ClaimBearer Token▾

Add a custom token claim to the application OIDC configuration. Custom claims map user attributes to access tokens and/or ID tokens, optionally applying a regex transformation rule.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Request Body

NameTypeRequiredDescription
namestringRequiredThe claim name as it will appear in the token.e.g. department
userAttributestringRequiredThe user profile attribute to map to this claim.e.g. department
regexRuleIdstringOptionalOptional ID of a regex rule to transform the claim value before inclusion in the token.e.g. rule_01hxyz
targetTokensstring[]RequiredWhich tokens should include this claim.e.g. ["ACCESS_TOKEN", "ID_TOKEN"]
ACCESS_TOKENID_TOKEN

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique claim ID.e.g. claim_01hxyz
namestringOptionalClaim name.e.g. department
userAttributestringOptionalMapped user attribute.e.g. department
regexRuleIdstring | nullOptionalAssociated regex rule ID, or null if none.e.g. null
targetTokensstring[]OptionalTarget tokens for the claim.e.g. ["ACCESS_TOKEN", "ID_TOKEN"]
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "id": "claim_01hxyz",
  "name": "department",
  "userAttribute": "department",
  "regexRuleId": null,
  "targetTokens": [
    "ACCESS_TOKEN",
    "ID_TOKEN"
  ],
  "createdAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/claims" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "department",
    "userAttribute": "department",
    "targetTokens": ["ACCESS_TOKEN", "ID_TOKEN"]
  }'
GET/api/v1/applications/:appId/oidc-config/claimsList ClaimsBearer Token▾

List all configured token claims for the application, including the user attribute mapping and target tokens.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
[]object[]OptionalArray of claim objects.
[].idstringOptionalUnique claim ID.e.g. claim_01hxyz
[].namestringOptionalClaim name.e.g. department
[].userAttributestringOptionalMapped user attribute.e.g. department
[].regexRuleIdstring | nullOptionalAssociated regex rule ID, or null.e.g. null
[].targetTokensstring[]OptionalTarget tokens for the claim.e.g. ["ID_TOKEN"]
[].createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "data": [
    {
      "id": "claim_01hxyz",
      "name": "department",
      "userAttribute": "department",
      "regexRuleId": null,
      "targetTokens": [
        "ID_TOKEN"
      ],
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "claim_02hxyz",
      "name": "email_domain",
      "userAttribute": "email",
      "regexRuleId": "rule_01hxyz",
      "targetTokens": [
        "ACCESS_TOKEN",
        "ID_TOKEN"
      ],
      "createdAt": "2025-01-16T08:00:00Z"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/claims" \
  -H "Authorization: Bearer <token>"
POST/api/v1/applications/:appId/oidc-config/regex-rulesCreate Regex RuleBearer Token▾

Add a claim transformation regex rule. Regex rules can be referenced by custom claims to transform user attribute values before they are included in tokens.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Request Body

NameTypeRequiredDescription
namestringRequiredA descriptive name for the regex rule.e.g. Extract domain
patternstringRequiredThe regular expression pattern to match against the claim value.e.g. ^.+@(.+)$
replacementstringRequiredThe replacement string (supports capture group references like $1).e.g. $1
flagsstringOptionalOptional regex flags (e.g. "i" for case-insensitive, "g" for global).e.g. i

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique regex rule ID.e.g. rule_01hxyz
namestringOptionalRule name.e.g. Extract domain
patternstringOptionalRegex pattern.e.g. ^.+@(.+)$
replacementstringOptionalReplacement string.e.g. $1
flagsstringOptionalRegex flags.e.g. i
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "id": "rule_01hxyz",
  "name": "Extract domain",
  "pattern": "^.+@(.+)$",
  "replacement": "$1",
  "flags": "i",
  "createdAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/regex-rules" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Extract domain",
    "pattern": "^.+@(.+)$",
    "replacement": "$1",
    "flags": "i"
  }'
GET/api/v1/applications/:appId/oidc-config/regex-rulesList Regex RulesBearer Token▾

List all claim transformation regex rules configured for the application.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
[]object[]OptionalArray of regex rule objects.
[].idstringOptionalUnique regex rule ID.e.g. rule_01hxyz
[].namestringOptionalRule name.e.g. Extract domain
[].patternstringOptionalRegex pattern.e.g. ^.+@(.+)$
[].replacementstringOptionalReplacement string.e.g. $1
[].flagsstringOptionalRegex flags.e.g. i
[].createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "data": [
    {
      "id": "rule_01hxyz",
      "name": "Extract domain",
      "pattern": "^.+@(.+)$",
      "replacement": "$1",
      "flags": "i",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "rule_02hxyz",
      "name": "Normalize username",
      "pattern": "\\s+",
      "replacement": "_",
      "flags": "g",
      "createdAt": "2025-01-16T08:00:00Z"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/regex-rules" \
  -H "Authorization: Bearer <token>"
POST/api/v1/applications/:appId/oidc-config/signing-keysCreate Signing KeyBearer Token▾

Add a signing key for token issuance. Signing keys are used to sign access tokens and ID tokens. Multiple keys can be configured to support key rotation.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Request Body

NameTypeRequiredDescription
kidstringRequiredKey identifier (kid) — a unique string used to identify this key in JWKS.e.g. sig-rs256-2025
algorithmstringRequiredThe JWS algorithm used for signing.e.g. RS256
RS256RS384RS512ES256ES384ES512PS256PS384PS512
publicKeystringRequiredPEM-encoded public key.e.g. -----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqh...\n-----END PUBLIC KEY-----
privateKeystringRequiredPEM-encoded private key.e.g. -----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBg...\n-----END PRIVATE KEY-----
certChainstringOptionalOptional PEM-encoded X.509 certificate chain.e.g. -----BEGIN CERTIFICATE-----\nMIIDdzCCAl+gAw...\n-----END CERTIFICATE-----
isDefaultbooleanOptionalWhether this key should be the default signing key.e.g. true

Response Fields

NameTypeRequiredDescription
idstringOptionalUnique signing key ID.e.g. key_01hxyz
kidstringOptionalKey identifier.e.g. sig-rs256-2025
algorithmstringOptionalJWS algorithm.e.g. RS256
isDefaultbooleanOptionalWhether this is the default signing key.e.g. true
createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "id": "key_01hxyz",
  "kid": "sig-rs256-2025",
  "algorithm": "RS256",
  "isDefault": true,
  "createdAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/signing-keys" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "kid": "sig-rs256-2025",
    "algorithm": "RS256",
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqh...\n-----END PUBLIC KEY-----",
    "privateKey": "-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBg...\n-----END PRIVATE KEY-----",
    "isDefault": true
  }'
GET/api/v1/applications/:appId/oidc-config/signing-keysList Signing KeysBearer Token▾

List all signing keys configured for the application. Private key material is not included in the response.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
[]object[]OptionalArray of signing key objects.
[].idstringOptionalUnique signing key ID.e.g. key_01hxyz
[].kidstringOptionalKey identifier.e.g. sig-rs256-2025
[].algorithmstringOptionalJWS algorithm.e.g. RS256
[].isDefaultbooleanOptionalWhether this is the default signing key.e.g. true
[].createdAtstringOptionalISO 8601 creation timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "data": [
    {
      "id": "key_01hxyz",
      "kid": "sig-rs256-2025",
      "algorithm": "RS256",
      "isDefault": true,
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "key_02hxyz",
      "kid": "sig-es256-2025",
      "algorithm": "ES256",
      "isDefault": false,
      "createdAt": "2025-01-16T08:00:00Z"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/signing-keys" \
  -H "Authorization: Bearer <token>"
PUT/api/v1/applications/:appId/oidc-config/token-policyUpdate Token PolicyBearer Token▾

Configure token lifetimes and refresh token rotation policy for the application. All fields are optional; only provided fields are updated.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Request Body

NameTypeRequiredDescription
accessTokenLifetimenumberOptionalAccess token lifetime in seconds (60 - 31536000).e.g. 3600
idTokenLifetimenumberOptionalID token lifetime in seconds (60 - 31536000).e.g. 3600
refreshTokenLifetimenumberOptionalRefresh token lifetime in seconds (3600 - 315360000).e.g. 86400
rotationEnabledbooleanOptionalWhether refresh token rotation is enabled. When enabled, a new refresh token is issued on each use.e.g. true
reuseIntervalnumberOptionalGrace period in seconds (0 - 3600) during which a rotated refresh token can still be reused.e.g. 0

Response Fields

NameTypeRequiredDescription
accessTokenLifetimenumberOptionalAccess token lifetime in seconds.e.g. 3600
idTokenLifetimenumberOptionalID token lifetime in seconds.e.g. 3600
refreshTokenLifetimenumberOptionalRefresh token lifetime in seconds.e.g. 86400
rotationEnabledbooleanOptionalWhether refresh token rotation is enabled.e.g. true
reuseIntervalnumberOptionalRefresh token reuse interval in seconds.e.g. 0
updatedAtstringOptionalISO 8601 last-updated timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "accessTokenLifetime": 3600,
  "idTokenLifetime": 3600,
  "refreshTokenLifetime": 86400,
  "rotationEnabled": true,
  "reuseInterval": 0,
  "updatedAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X PUT "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/token-policy" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "accessTokenLifetime": 3600,
    "idTokenLifetime": 3600,
    "refreshTokenLifetime": 86400,
    "rotationEnabled": true,
    "reuseInterval": 0
  }'
GET/api/v1/applications/:appId/oidc-config/token-policyGet Token PolicyBearer Token▾

Get the current token policy settings for the application, including access token, ID token, and refresh token lifetimes, as well as rotation configuration.

Parameters

NameTypeRequiredDescription
appIdstringRequiredThe unique identifier of the application.e.g. app_01hxyz

Response Fields

NameTypeRequiredDescription
accessTokenLifetimenumberOptionalAccess token lifetime in seconds.e.g. 3600
idTokenLifetimenumberOptionalID token lifetime in seconds.e.g. 3600
refreshTokenLifetimenumberOptionalRefresh token lifetime in seconds.e.g. 86400
rotationEnabledbooleanOptionalWhether refresh token rotation is enabled.e.g. true
reuseIntervalnumberOptionalRefresh token reuse interval in seconds.e.g. 0
updatedAtstringOptionalISO 8601 last-updated timestamp.e.g. 2025-01-15T10:30:00Z

Response Example

{
  "accessTokenLifetime": 3600,
  "idTokenLifetime": 3600,
  "refreshTokenLifetime": 86400,
  "rotationEnabled": true,
  "reuseInterval": 0,
  "updatedAt": "2025-01-15T10:30:00Z"
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/applications/app_01hxyz/oidc-config/token-policy" \
  -H "Authorization: Bearer <token>"