OIDC Provider

SutraID as an OpenID Connect Identity Provider — authorization, token, userinfo, and JWKS endpoints.

GET/api/v1/sso/oidc-idp/:orgId/.well-known/openid-configurationOIDC Discovery▾

Returns the OpenID Connect discovery document for the specified organization. Clients can use this to auto-configure OIDC integration without hardcoding endpoint URLs.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization acting as the OIDC IdP.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`

Response Fields

Name	Type	Required	Description
`issuer`	string	Optional	The issuer URL for this IdP.e.g. `https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v`
`authorization_endpoint`	string	Optional	URL of the authorization endpoint.
`token_endpoint`	string	Optional	URL of the token endpoint.
`userinfo_endpoint`	string	Optional	URL of the userinfo endpoint.
`jwks_uri`	string	Optional	URL of the JSON Web Key Set document.
`scopes_supported`	string[]	Optional	List of OAuth 2.0 scopes supported.e.g. `["openid","email","profile"]`
`response_types_supported`	string[]	Optional	List of response types supported.e.g. `["code"]`
`grant_types_supported`	string[]	Optional	List of grant types supported.e.g. `["authorization_code","refresh_token"]`
`subject_types_supported`	string[]	Optional	Subject identifier types supported.e.g. `["public"]`
`id_token_signing_alg_values_supported`	string[]	Optional	ID token signing algorithms supported.e.g. `["RS256"]`

Response Example

{
  "issuer": "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v",
  "authorization_endpoint": "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/authorize",
  "token_endpoint": "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/token",
  "userinfo_endpoint": "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/userinfo",
  "jwks_uri": "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/jwks",
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "response_types_supported": [
    "code"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/.well-known/openid-configuration"

GET/api/v1/sso/oidc-idp/:orgId/authorizeAuthorization Endpoint▾

Initiates the OIDC authorization flow. The user is redirected to the SutraID login page (or consent screen if already authenticated). Supports PKCE for public clients.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`
`client_id`	string	Required	The client application identifier.e.g. `app_01hx9k2m3n4p5q6r7s8t9u0v`
`redirect_uri`	string	Required	URI to redirect the user to after authorization. Must match a registered redirect URI.e.g. `https://yourapp.com/callback`
`scope`	string	Required	Space-separated list of requested scopes.e.g. `openid email profile`
`response_type`	string	Required	Must be "code" for authorization code flow.e.g. `code` `code`
`state`	string	Required	Opaque value used to maintain state between request and callback. Protects against CSRF.e.g. `xK9mP2qR5tU8wZ1aB4cD7eF0`
`code_challenge`	string	Optional	PKCE code challenge (Base64URL-encoded SHA-256 hash of code_verifier).e.g. `E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM`
`code_challenge_method`	string	Optional	PKCE challenge method. Must be "S256" when code_challenge is provided.e.g. `S256` `S256`
`nonce`	string	Optional	Random value to associate the client session with the ID token, mitigating replay attacks.e.g. `n-0S6_WzA2Mj`

Response Fields

Name	Type	Required	Description
`302 Location`	string	Optional	Redirect to login or consent page. On completion, redirects back to redirect_uri with code and state query parameters.

Response Example

{
  "_note": "HTTP 302 redirect — no JSON body. On success the user is redirected to redirect_uri?code=AUTH_CODE&state=STATE"
}

Code Examples

# Open this URL in a browser — it initiates the authorization flow with PKCE
curl -v -L "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/authorize?client_id=app_01hx9k2m3n4p5q6r7s8t9u0v&redirect_uri=https%3A%2F%2Fyourapp.com%2Fcallback&scope=openid%20email%20profile&response_type=code&state=xK9mP2qR5tU8wZ1aB4cD7eF0&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256"

POST/api/v1/sso/oidc-idp/:orgId/tokenToken Endpoint▾

Exchanges an authorization code for an access token, ID token, and optional refresh token. Accepts application/x-www-form-urlencoded. Supports PKCE via code_verifier.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`

Request Body

Name	Type	Required	Description
`grant_type`	string	Required	Must be "authorization_code".e.g. `authorization_code` `authorization_code`
`code`	string	Required	The authorization code received from the authorization endpoint.e.g. `SplxlOBeZQQYbYS6WxSbIA`
`redirect_uri`	string	Required	Must match the redirect_uri used in the authorization request.e.g. `https://yourapp.com/callback`
`client_id`	string	Required	The client application identifier.e.g. `app_01hx9k2m3n4p5q6r7s8t9u0v`
`client_secret`	string	Optional	Client secret for confidential clients. Omit for public clients using PKCE.e.g. `cs_live_01hx9k2m3n4p5q6r7s8t9u0v`
`code_verifier`	string	Optional	PKCE code verifier. Required for public clients that sent a code_challenge.e.g. `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk`

Response Fields

Name	Type	Required	Description
`access_token`	string	Optional	JWT access token for accessing protected resources.
`id_token`	string	Optional	JWT ID token containing user identity claims.
`refresh_token`	string	Optional	Refresh token for obtaining new access tokens (if offline_access scope was requested).
`token_type`	string	Optional	Always "Bearer".e.g. `Bearer`
`expires_in`	number	Optional	Access token lifetime in seconds.e.g. `3600`

Response Example

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDFoeDlrMm0zbjRwNXE2cjdzOHQ5dTB2IiwiaWF0IjoxNzAwMDAwMDAwfQ.signature",
  "id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c3JfMDFoeDlrMm0zbjRwNXE2cjdzOHQ5dTB2IiwiZW1haWwiOiJhbGljZUBleGFtcGxlLmNvbSJ9.signature",
  "refresh_token": "v1.MRjRnAKY5uDhtbnO5xSNBzuP9ZGFVNWJm6KH7nE",
  "token_type": "Bearer",
  "expires_in": 3600
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" \
  --data-urlencode "code=SplxlOBeZQQYbYS6WxSbIA" \
  --data-urlencode "redirect_uri=https://yourapp.com/callback" \
  --data-urlencode "client_id=app_01hx9k2m3n4p5q6r7s8t9u0v" \
  --data-urlencode "code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"

GET/api/v1/sso/oidc-idp/:orgId/userinfoUserInfo EndpointBearer Token▾

Returns identity claims for the authenticated user. Requires a valid access token obtained from the token endpoint. Scope claims returned depend on the scopes granted during authorization.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`
`Authorization`	string	Required	Bearer access token obtained from the token endpoint.e.g. `Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...`

Response Fields

Name	Type	Required	Description
`sub`	string	Optional	Subject identifier — the unique user ID.e.g. `usr_01hx9k2m3n4p5q6r7s8t9u0v`
`email`	string	Optional	User email address.e.g. `alice@example.com`
`name`	string	Optional	Full display name.e.g. `Alice Smith`
`given_name`	string	Optional	First/given name.e.g. `Alice`
`family_name`	string	Optional	Last/family name.e.g. `Smith`
`email_verified`	boolean	Optional	Whether the email address has been verified.e.g. `true`

Response Example

{
  "sub": "usr_01hx9k2m3n4p5q6r7s8t9u0v",
  "email": "alice@example.com",
  "name": "Alice Smith",
  "given_name": "Alice",
  "family_name": "Smith",
  "email_verified": true
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/userinfo" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

GET/api/v1/sso/oidc-idp/:orgId/jwksJSON Web Key Set▾

Returns the public keys used by SutraID to sign ID tokens and access tokens for the specified organization. Relying parties use this to verify JWT signatures.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`

Response Fields

Name	Type	Required	Description
`keys`	object[]	Optional	Array of JSON Web Keys.
`keys[].kty`	string	Optional	Key type (e.g., "RSA").e.g. `RSA`
`keys[].kid`	string	Optional	Key identifier.e.g. `key_01hx9k2m3n4p5q6r7s8t9u0v`
`keys[].use`	string	Optional	Intended use of the key ("sig" for signature).e.g. `sig`
`keys[].alg`	string	Optional	Algorithm associated with the key.e.g. `RS256`
`keys[].n`	string	Optional	RSA public key modulus (Base64URL-encoded).
`keys[].e`	string	Optional	RSA public key exponent (Base64URL-encoded).e.g. `AQAB`

Response Example

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "key_01hx9k2m3n4p5q6r7s8t9u0v",
      "use": "sig",
      "alg": "RS256",
      "n": "pjdss8ZaDfEH6K6U7GeW2nxDqR4IP049fk1fK0lndimbMMVBdPv_hSpm8T8EtBDxrUdi1OHZfMhUixGyw-g",
      "e": "AQAB"
    }
  ]
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/jwks"

GET/api/v1/sso/oidc-idp/:orgId/interaction/:uidGet Consent Interaction DetailsBearer Token▾

Retrieves details about a pending consent interaction, including the application requesting access and the scopes being requested. Used to render a consent screen to the user.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`
`uid`	string	Required	The unique identifier of the interaction session.e.g. `int_01hx9k2m3n4p5q6r7s8t9u0v`
`Authorization`	string	Required	Bearer JWT token for the authenticated user.e.g. `Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...`

Response Fields

Name	Type	Required	Description
`uid`	string	Optional	The interaction session identifier.e.g. `int_01hx9k2m3n4p5q6r7s8t9u0v`
`application.id`	string	Optional	The requesting application ID.e.g. `app_01hx9k2m3n4p5q6r7s8t9u0v`
`application.name`	string	Optional	Display name of the requesting application.e.g. `My SaaS App`
`application.description`	string	Optional	Description of the requesting application.
`application.logoUrl`	string	Optional	URL to the application logo.
`scopes`	string[]	Optional	List of scopes being requested.e.g. `["openid","email","profile"]`
`redirectUri`	string	Optional	The URI to which the user will be redirected after consent.e.g. `https://yourapp.com/callback`

Response Example

{
  "uid": "int_01hx9k2m3n4p5q6r7s8t9u0v",
  "application": {
    "id": "app_01hx9k2m3n4p5q6r7s8t9u0v",
    "name": "My SaaS App",
    "description": "A business productivity application.",
    "logoUrl": "https://yourapp.com/logo.png"
  },
  "scopes": [
    "openid",
    "email",
    "profile"
  ],
  "redirectUri": "https://yourapp.com/callback"
}

Code Examples

curl -X GET "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/interaction/int_01hx9k2m3n4p5q6r7s8t9u0v" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

POST/api/v1/sso/oidc-idp/:orgId/interaction/:uid/confirmConfirm ConsentBearer Token▾

Submits the user's consent decision for a pending OIDC interaction. When consent is true, the authorization code flow completes and the user is redirected to the client application.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`
`uid`	string	Required	The unique identifier of the interaction session.e.g. `int_01hx9k2m3n4p5q6r7s8t9u0v`
`Authorization`	string	Required	Bearer JWT token for the authenticated user.e.g. `Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...`

Request Body

Name	Type	Required	Description
`consent`	boolean	Required	true to grant consent, false to deny.e.g. `true`

Response Fields

Name	Type	Required	Description
`success`	boolean	Optional	Whether consent was processed successfully.e.g. `true`
`redirectTo`	string	Optional	The URL the client application should redirect the user to.e.g. `https://yourapp.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xK9mP2qR5tU8wZ1aB4cD7eF0`

Response Example

{
  "success": true,
  "redirectTo": "https://yourapp.com/callback?code=SplxlOBeZQQYbYS6WxSbIA&state=xK9mP2qR5tU8wZ1aB4cD7eF0"
}

Code Examples

curl -X POST "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/interaction/int_01hx9k2m3n4p5q6r7s8t9u0v/confirm" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{"consent": true}'

GET/api/v1/sso/oidc-idp/:orgId/end-sessionEnd Session (Logout)▾

Ends the user's SSO session at the SutraID IdP and optionally redirects to a post-logout URI. Implements the OpenID Connect RP-Initiated Logout specification.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`
`id_token_hint`	string	Optional	Previously issued ID token, used to identify the user being logged out.e.g. `eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...`
`post_logout_redirect_uri`	string	Optional	URI to redirect the user to after logout. Must be registered with the client.e.g. `https://yourapp.com/logged-out`
`state`	string	Optional	Opaque value passed back to the client in the post_logout_redirect_uri.e.g. `xK9mP2qR5tU8wZ1aB4cD7eF0`

Response Fields

Name	Type	Required	Description
`302 Location`	string	Optional	HTTP 302 redirect to post_logout_redirect_uri (with state if provided), or to the SutraID default logged-out page.

Response Example

{
  "_note": "HTTP 302 redirect — no JSON body. User is redirected to post_logout_redirect_uri?state=STATE or the default logout page."
}

Code Examples

curl -v -L "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/end-session?id_token_hint=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...&post_logout_redirect_uri=https%3A%2F%2Fyourapp.com%2Flogged-out&state=xK9mP2qR5tU8wZ1aB4cD7eF0"

GET/api/v1/sso/oidc-idp/:orgId/*OIDC Provider Catch-All▾

Wildcard route that forwards any unmatched requests to the underlying oidc-provider library. This handles additional protocol interactions such as device authorization, pushed authorization requests, and other oidc-provider internal routes.

Parameters

Name	Type	Required	Description
`orgId`	string	Required	The unique identifier of the organization.e.g. `org_01hx9k2m3n4p5q6r7s8t9u0v`

Response Fields

Name	Type	Required	Description
`varies`	any	Optional	Response format depends on the specific oidc-provider route being accessed.

Response Example

{
  "_note": "Response varies by route. This catch-all proxies to the oidc-provider library for any path under /api/v1/sso/oidc-idp/:orgId/ not covered by a dedicated endpoint."
}

Code Examples

# Example: access the oidc-provider check_session iframe endpoint
curl -X GET "https://api.sutraid.com/api/v1/sso/oidc-idp/org_01hx9k2m3n4p5q6r7s8t9u0v/session/check"