External OpenID providers

Create external OpenID provider

POST/v4/config/ows/issuer/openid-providers

Adds an external OpenID provider to the organisation. In an authorisation code issuance of a credential definition that names the provider (externalOpenidProviderId, OpenID4VCI 1.0 definitions only), the holder logs in at this provider, and the API exchanges the code with the client ID and the client secret. With claimsGatheringCallbackUri, a deferred issuance gets its claims from that URL.

The client secret is write-only: the response has clientSecretConfigured, never the secret.

Language of the request sample

curl -X POST 'https://demo-api.igrant.io/v4/config/ows/issuer/openid-providers' \
  -H 'Authorization: ApiKey <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Example Bank login",
  "issuer": "https://login.example-bank.com",
  "clientId": "igrant-issuer",
  "clientSecret": "<client-secret>",
  "scopes": "openid profile email",
  "claimsGatheringCallbackUri": "https://issuer.example-bank.com/claims"
}'

{
  "oidcProvider": {
    "id": "3f6c2a9e-7b1d-4c58-9e2f-1a4b6d8c0e57",
    "name": "Example Bank login",
    "issuer": "https://login.example-bank.com",
    "clientId": "igrant-issuer",
    "clientSecretConfigured": true,
    "scopes": "openid profile email",
    "claimsGatheringCallbackUri": "https://issuer.example-bank.com/claims",
    "isBuiltInConformance": false,
    "createdAt": 1794365298,
    "updatedAt": 1794365298
  }
}

Authorizations

Authorizationstringheaderrequired
Your API key with the prefix ApiKey: ApiKey <your-api-key>. Get an API key.
Scope:authorization-servers:create

Body

application/json

namestringrequired
The name of the provider. Required.
At most 255 characters.
Example:"Example Bank login"
issuerstringrequired
The issuer identifier of the provider: an http(s) URL. A trailing / is removed. Required.
At most 2048 characters.
Example:"https://login.example-bank.com"
clientIdstringrequired
The client ID of the issuer at the provider. Required.
At most 255 characters.
Example:"igrant-issuer"
clientSecretstringrequired
The client secret of the issuer at the provider, for its token endpoint. Required to create a provider. In an update, leave it out (or send an empty text) to keep the stored secret.
At most 4096 characters.
Example:"<client-secret>"
scopesstring
The scopes to ask for at the provider, separated by spaces. The API adds openid when it is missing. Empty or left out: openid profile email.
At most 255 characters.
Default:openid profile email
Example:"openid profile email"
claimsGatheringCallbackUristring
An http(s) URL where the API gets the claims of a deferred issuance. The API calls it with the access token of the holder from the provider as bearer token, and the URL answers {"claims": {...}}, {"interval": <seconds>} (not ready yet) or {"issuanceDenied": true, "issuanceDeniedReason": "..."}. In an update, leave it out (or send an empty text) to remove the stored URL.
At most 2048 characters.
Example:"https://issuer.example-bank.com/claims"

Response

application/json

The provider is stored.

oidcProviderobject
An external OpenID provider of the organisation: the OpenID Connect provider where the holder logs in during an authorisation code issuance of a credential definition that names it (externalOpenidProviderId). The client secret is write-only: the response only says whether one is stored (clientSecretConfigured).