light-mode-image
Learn
Claims source

API Reference

Configure a Claims source

Configure a claims source

Configures a new claims source for your tenant. When issuing a new credential, MATTR VII will make either a GET or a POST request to the claims source using the configured request parameters and fetch available data. This fetched data can then be included in the issued credential.

Analytic event

  • CLAIM_SOURCE_CREATE_START
  • CLAIM_SOURCE_CREATE_SUCCESS
  • CLAIM_SOURCE_CREATE_FAIL
POST/v1/claim-sources

Authorization

AuthorizationBearer <token>

In: header

Request Body

The claim source payload

namestring

Claims source name.

urlstring

Claims source URL (and any redirects it may include):

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters.
  • Unicode will be converted to ASCII.
requestMethod?string

Indicates the request method MATTR VII will use when retrieving data from this claims source. Both the GET and POST method are supported. If no value is provided, GET is used by default. When using POST, all requestParameters must be included in the request body in JSON format.

Value in"GET" | "POST"
requestParametersMapping only | Mapping with fallback | Static value

Use this object to define how to map request parameters that are sent to your claims source using the mapFrom and defaultValue properties:

  • When only providing mapFrom, the request parameter will be mapped from the defined path. If mapping fails, no alternative value is used. You can map data from both the claims and credentialConfiguration objects.
  • When providing both mapFrom and defaultValue, MATTR VII will attempt to map the request parameter from the defined path. If mapping fails, the defaultValue is used instead.
  • When only providing defaultValue, its value is used to populate the request parameter, regardless of any available claims values.
mapFromstring

Path to map the claim from.

mapFromstring

Path to map the claim from.

defaultValuestring | array<unknown> | object

Static value to be used when mapFrom fails or evaluated to undefined (attribute doesn't exist).

Empty Object

defaultValuestring | array<unknown> | object

Static value to be used for all issued credentials, without querying the claims source.

Empty Object

authorizationAPI Key | OAuth Client Credentials

Authentication method configuration to access the claims source.

API Key used to authenticate the request to the claims source server.

typestring
Value in"api-key"
value?string

API key value. Note that MATTR VII does not validate your input, which means it's up to you to provide the correct API key for your claim sources.

OAuth client credentials used for getting an access token for the claim source.

typestring
Value in"oauth-client-credentials"
tokenEndpointstring

OAuth 2.0 token endpoint URL for obtaining an access token for this claims source.

Formaturl
clientIdstring

Your client identifier for this claims source.

clientSecret?string

OAuth 2.0 client secret that will be used for the token endpoint request.

tokenEndpointAuthMethod?string

Two authentication methods are available:

  • client_secret_basic (default): Credentials are passed as a base 64 encoded basic token.
  • client_secret_post: Credentials are passed as parameters within the request body.
Value in"client_secret_basic" | "client_secret_post"
audience?string

Optional audience for the claims source token.

curl -X POST "https://example.vii.au01.mattr.global/v1/claim-sources" \  -H "Content-Type: application/json" \  -d '{    "name": "Claims source accepting a x-api-key header",    "url": "https://example.com/api/data",    "authorization": {      "type": "api-key",      "value": "6hrFDATxrG9w14QY9wwnmVhLE0Wg6LIvwOwUaxz761m1J"    },    "requestParameters": {      "account_type": {        "mapFrom": "claims.accountType",        "defaultValue": "account.student"      },      "account_id": {        "mapFrom": "claims.accountId"      }    }  }'

{
  "name": "Claims source accepting a x-api-key header",
  "url": "https://example.com/api/data",
  "authorization": {
    "type": "api-key",
    "value": "****************************************61m1J"
  },
  "requestParameters": {
    "account_type": {
      "mapFrom": "claims.accountType",
      "defaultValue": "account.student"
    },
    "account_id": {
      "mapFrom": "claims.accountId"
    }
  }
}

{
  "code": "BadRequest",
  "message": "Validation Error",
  "details": [
    {
      "location": "body",
      "msg": "Invalid value",
      "param": "url"
    }
  ]
}

Retrieve all Claim sources

Retrieve all claims sources

Returns a list of all claims sources configured on your tenant.

Analytic event

  • CLAIM_SOURCE_RETRIEVE_LIST_START
  • CLAIM_SOURCE_RETRIEVE_LIST_SUCCESS
  • CLAIM_SOURCE_RETRIEVE_LIST_FAIL
GET/v1/claim-sources

Authorization

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned entries, default 100

Range1 <= value <= 1000
cursor?string

Starting point for the range of entries

curl -X GET "https://example.vii.au01.mattr.global/v1/claim-sources?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h"
{
  "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  "data": [
    {
      "id": "57fa09e2-82f3-4d3d-9eca-d0253e84a4e6",
      "name": "My claims from example.com",
      "url": "https://example.com",
      "requestMethod": "GET",
      "requestParameters": {
        "mapFrom": "claims.accountType"
      },
      "authorization": {
        "type": "api-key",
        "value": "****************************************61m1J"
      }
    }
  ]
}

{
  "code": "BadRequest",
  "message": "Validation Error",
  "details": [
    {
      "location": "query",
      "msg": "Invalid value",
      "param": "cursor",
      "value": "abc"
    }
  ]
}

Retrieve a Claim source

Retrieve a claims source

Retrieves an existing claims source by providing its claimSourceID.

Analytic event

  • CLAIM_SOURCE_RETRIEVE_START
  • CLAIM_SOURCE_RETRIEVE_SUCCESS
  • CLAIM_SOURCE_RETRIEVE_FAIL
GET/v1/claim-sources/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Claims source ID

Formatuuid
curl -X GET "https://example.vii.au01.mattr.global/v1/claim-sources/41458e5a-9092-40b7-9a26-d4eb43c5792f"
{
  "id": "57fa09e2-82f3-4d3d-9eca-d0253e84a4e6",
  "name": "My claims from example.com",
  "url": "https://example.com",
  "requestMethod": "GET",
  "requestParameters": {
    "mapFrom": "claims.accountType"
  },
  "authorization": {
    "type": "api-key",
    "value": "****************************************61m1J"
  }
}

{
  "code": "BadRequest",
  "message": "Validation Error",
  "details": [
    {
      "location": "params",
      "msg": "Invalid value",
      "param": "claimSourceId",
      "value": "abc"
    }
  ]
}

{
  "code": "NotFound",
  "message": "Validation Error",
  "details": [
    {
      "location": "params",
      "msg": "Resource Not Found",
      "param": "claimSourceId",
      "value": "a368cfb4-9537-4439-acc6-ce3cf2287eb7"
    }
  ]
}

Update a Claim source

Update a claims source

Updates an existing claim source by providing its claimSourceID.

Analytic event

  • CLAIM_SOURCE_UPDATE_START
  • CLAIM_SOURCE_UPDATE_SUCCESS
  • CLAIM_SOURCE_UPDATE_FAIL
PUT/v1/claim-sources/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Claims source ID

Formatuuid

Request Body

The updated claims source payload

namestring

Claims source name.

urlstring

Claims source URL (and any redirects it may include):

  • Must be a valid URL.
  • Must use the HTTPS protocol.
  • Must not be an IP address.
  • Must not include query parameters.
  • Unicode will be converted to ASCII.
requestMethod?string

Indicates the request method MATTR VII will use when retrieving data from this claims source. Both the GET and POST method are supported. If no value is provided, GET is used by default. When using POST, all requestParameters must be included in the request body in JSON format.

Value in"GET" | "POST"
requestParametersMapping only | Mapping with fallback | Static value

Use this object to define how to map request parameters that are sent to your claims source using the mapFrom and defaultValue properties:

  • When only providing mapFrom, the request parameter will be mapped from the defined path. If mapping fails, no alternative value is used. You can map data from both the claims and credentialConfiguration objects.
  • When providing both mapFrom and defaultValue, MATTR VII will attempt to map the request parameter from the defined path. If mapping fails, the defaultValue is used instead.
  • When only providing defaultValue, its value is used to populate the request parameter, regardless of any available claims values.
mapFromstring

Path to map the claim from.

mapFromstring

Path to map the claim from.

defaultValuestring | array<unknown> | object

Static value to be used when mapFrom fails or evaluated to undefined (attribute doesn't exist).

Empty Object

defaultValuestring | array<unknown> | object

Static value to be used for all issued credentials, without querying the claims source.

Empty Object

authorizationAPI Key | OAuth Client Credentials

Authentication method configuration to access the claims source.

API Key used to authenticate the request to the claims source server.

typestring
Value in"api-key"
value?string

API key value. Note that MATTR VII does not validate your input, which means it's up to you to provide the correct API key for your claim sources.

OAuth client credentials used for getting an access token for the claim source.

typestring
Value in"oauth-client-credentials"
tokenEndpointstring

OAuth 2.0 token endpoint URL for obtaining an access token for this claims source.

Formaturl
clientIdstring

Your client identifier for this claims source.

clientSecret?string

OAuth 2.0 client secret that will be used for the token endpoint request.

tokenEndpointAuthMethod?string

Two authentication methods are available:

  • client_secret_basic (default): Credentials are passed as a base 64 encoded basic token.
  • client_secret_post: Credentials are passed as parameters within the request body.
Value in"client_secret_basic" | "client_secret_post"
audience?string

Optional audience for the claims source token.

curl -X PUT "https://example.vii.au01.mattr.global/v1/claim-sources/41458e5a-9092-40b7-9a26-d4eb43c5792f" \  -H "Content-Type: application/json" \  -d '{    "name": "My claims from example.com",    "url": "https://example.com",    "requestParameters": {      "mapFrom": "claims.accountType"    },    "authorization": {      "type": "api-key"    }  }'
{
  "id": "57fa09e2-82f3-4d3d-9eca-d0253e84a4e6",
  "name": "My claims from example.com",
  "url": "https://example.com",
  "requestMethod": "GET",
  "requestParameters": {
    "mapFrom": "claims.accountType"
  },
  "authorization": {
    "type": "api-key",
    "value": "****************************************61m1J"
  }
}

{
  "code": "BadRequest",
  "message": "Validation Error",
  "details": [
    {
      "location": "body",
      "msg": "Invalid value",
      "param": "url"
    }
  ]
}

{
  "code": "NotFound",
  "message": "Validation Error",
  "details": [
    {
      "location": "params",
      "msg": "Resource Not Found",
      "param": "claimSourceId",
      "value": "a368cfb4-9537-4439-acc6-ce3cf2287eb7"
    }
  ]
}

Delete a Claim source

Delete a claims source

Deletes an existing claims source by providing its claimSourceID.

Analytic event

  • CLAIM_SOURCE_DELETE_START
  • CLAIM_SOURCE_DELETE_SUCCESS
  • CLAIM_SOURCE_DELETE_FAIL
DELETE/v1/claim-sources/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Claims source ID

Formatuuid
curl -X DELETE "https://example.vii.au01.mattr.global/v1/claim-sources/41458e5a-9092-40b7-9a26-d4eb43c5792f"
Empty

{
  "code": "BadRequest",
  "message": "Validation Error",
  "details": [
    {
      "location": "params",
      "msg": "Invalid value",
      "param": "claimSourceId",
      "value": "abc"
    }
  ]
}

{
  "code": "NotFound",
  "message": "Validation Error",
  "details": [
    {
      "location": "params",
      "msg": "Resource Not Found",
      "param": "claimSourceId",
      "value": "a368cfb4-9537-4439-acc6-ce3cf2287eb7"
    }
  ]
}

How would you rate this page?

Tutorial

Previous Page

Overview

Next Page

On this page

Configure a Claims sourceRetrieve all Claim sourcesRetrieve a Claim sourceUpdate a Claim sourceDelete a Claim source