Attribute Providers

Attribute providers are external HTTPS endpoints that Paradym can call during OpenID4VC issuance to fetch attribute values for a credential. This lets you keep your source of truth in existing systems and populate credentials dynamically, instead of sending all attribute values when creating an offer, as well as defer the credential issuance.

Attribute providers also integrate with authorization servers. If a credential template is linked to an authorization server, the access token and ID token (when available) are forwarded to your attribute provider so you can retrieve attributes from protected APIs.

By using attribute providers, you can avoid storing personal data in Paradym entirely. Instead of sending attributes to Paradym during offer creation, your backend remains the system of record and provides only the data needed at issuance time.

If avoiding storing personal data in Paradym is your goal, and you’re using an authorization server, please note that ID tokens may contain personal information. Instead, we recommend not requesting an ID token and use the access token to retrieve the required information from the UserInfo  endpoint.

Configuring an Attribute Provider

When configuring an attribute provider, you need to provide the following information:

• The name of the attribute provider, allowing you to recognize it easily.
• The HTTPS URL of the endpoint where Paradym should request attributes.
• The authentication method, which is currently apiKey.

Once you have these details, you can configure an attribute provider using either the API or the Dashboard.

{
  "name": "Example Attribute Provider",
  "url": "https://attributes.example.com",
  "authentication": {
    "type": "apiKey",
    "apiKey": "my-attribute-provider-api-key"
  }
}

Configuring a Credential Template

Once you have configured an attribute provider, you can link it to SD-JWT VC and mDoc credential templates. When linked, Paradym will call the attribute provider during issuance to populate the credential attributes.

{
  "name": "OpenID Profile",
  "description": "This is your OpenID profile.",
  "issuer": {
    "signer": "certificate",
    "keyType": "P-256"
  },
  "type": "org.example.OpenIdProfile",
  "attributes": {
    "org.example.OpenIdProfile": {
      "properties": {
        "name": {
          "type": "string",
          "name": "Name",
          "required": true
        }
      }
    }
  },
  "attributeProviderId": "clu159ps100013evfbvhz22m1"
}

Request and Response Formats

Paradym always makes a POST request with a JSON body and includes the attribute provider API key in the X-Api-Key header. Your endpoint should return a JSON response that contains the attributes to include in the credential within 5 seconds. The response payload must be under 50 kB.

Request

type AttributeProviderRequest = {
  // The ID obtained when creating an OpenID4VCI offer.
  openId4VcIssuanceId: string
 
  // The template associated with this request. Either one is set.
  sdJwtVcCredentialTemplateId?: string
  mdocCredentialTemplateId?: string
 
  // Set if an authorization server has been configured. Only included in the
  // initial request, not in subsequent deferral requests.
  authorizationServer?: {
    id: string
    url: string
    accessToken: string
    idToken?: string
  }
}

Response

type AttributeProviderCredentialResponse = {
  type: "credential";
 
  // The attributes to fulfill the credential request.
  attributes: Record<string, unknown>;
}
 
type AttributeProviderDeferralResponse = {
  type: "deferral";
 
  // Positive number that representes the minimum amount of time that the wallet
  // SHOULD wait after receiving the response before sending a new request to
  // fetch the credential.
  intervalInMinutes: number;
}
 
type AttributeProviderResponse =
  | AttributeProviderCredentialResponse
  | AttributeProviderDeferralResponse

If the response is invalid or required attributes are missing, issuance will fail. Ensure that the returned attributes match the schema of the credential template.

When using an Attribute Provider, you are allowed to defer the issuance of the credential until the attributes are ready. However, there are some things you need to note:

• A credential issuance session has a fixed maximum lifetime of 30 days.
• Every time the Attribute Provider defers the issuance, the expiration date is recalculated to be one interval away plus the grace period (7 days). This gives the wallet enough time to check back.
• If the new expiration date is higher than 30 days, issuance will fail.

Here’s an example scenario:

• An issuance session starts on January 1st.
• Your attribute provider delays the issuance for 5 days. The new expiration date is now January 10th.
• On the 5th of January, the wallet checks if the credential is ready. You delay the issuance 5 more days. The expiration date is now January 15th.
• If you were to delay the issuance for 5 more days on January 25th, the expiration date would be more than 30 days after the creation of the session. Issuance would fail.

Relevant pages