light-mode-image
Learn
Credential configurationAPI Reference

Semantic CWT Credentials

Create a Semantic CWT Credential configuration

Create a Semantic CWT credentials configuration

Creates a new Semantic CWT credentials configuration, a specific set of rules and parameters that are used to create and validate a particular type of verifiable credential. These rules and parameters define how the credential is structured and what data it contains when issued.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_CREATE_FAIL
POST/v2/credentials/compact-semantic/configurations

Authorization

AuthorizationBearer <token>

In: header

Request Body

The Credential Configuration payload

type?unknown

Used to differentiate between different CWT/Semantic CWT credentials configurations on your tenant. Thus, its value must:

  • Be unique across all CWT/Semantic CWT credentials configurations on your tenant.
  • Not be VerifiableCredential.
Length1 <= length <= 1024
claimMappingscredentialConfigurationClaimMappings

This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

  • mapFrom: References the path in the user object where the claim is available.
    • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").
    • mapFrom is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
  • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.
  • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail. Example claims object inside the user object
{
  "claims": {
    "given_name": "Jamie",
    "family_name": "Doe",
    "address": {
      "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
    }
  },
  "authenticationProvider": {
    "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
    "url": "https://accounts.google.com"
  }
}

Empty Object

revocable?boolean

When set to true (default), the created credential can later be revoked. When set to false, the credential cannot be revoked.

Defaulttrue
claimSourceId?string

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

Formatuuid
expiresIn?object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

curl -X POST "https://example.vii.au01.mattr.global/v2/credentials/compact-semantic/configurations" \  -H "Content-Type: application/json" \  -d '{    "claimMappings": {      "firstName": {        "mapFrom": "claims.given_name",        "required": true      },      "address": {        "mapFrom": "claims.address.formatted"      },      "picture": {        "mapFrom": "claims.picture",        "defaultValue": "http://example.edu/img/placeholder.png"      },      "badge": {        "defaultValue": "http://example.edu/img/badge.png"      },      "providerSubjectId": {        "mapFrom": "authenticationProvider.subjectId"      }    }  }'
{
  "id": "983c0a86-204f-4431-9371-f5a22e506599",
  "type": "CourseCredential",
  "claimMappings": {
    "firstName": {
      "mapFrom": "claims.given_name",
      "required": true
    },
    "address": {
      "mapFrom": "claims.address.formatted"
    },
    "picture": {
      "mapFrom": "claims.picture",
      "defaultValue": "http://example.edu/img/placeholder.png"
    },
    "badge": {
      "defaultValue": "http://example.edu/img/badge.png"
    },
    "providerSubjectId": {
      "mapFrom": "authenticationProvider.subjectId"
    }
  },
  "revocable": true,
  "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  "expiresIn": {
    "years": 1,
    "months": 12,
    "weeks": 52,
    "days": 365,
    "hours": 24,
    "minutes": 1440,
    "seconds": 3600
  }
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Retrieve all Semantic CWT Credential configurations

Retrieve all Semantic CWT credentials configurations

Returns a list of all Compact Semantic Credential configurations from your tenant.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_LIST_FAIL
GET/v2/credentials/compact-semantic/configurations

Authorization

AuthorizationBearer <token>

In: header

Query Parameters

limit?number

Range size of returned list.

Default100
Range1 <= value <= 1000
cursor?string

Starting point for the list of entries.

type?string

The optional credential type to filter on

curl -X GET "https://example.vii.au01.mattr.global/v2/credentials/compact-semantic/configurations?limit=2&cursor=Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1h&type=AlumniCredential"
{
  "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM",
  "data": [
    {
      "id": "983c0a86-204f-4431-9371-f5a22e506599",
      "type": "CourseCredential",
      "claimMappings": {
        "firstName": {
          "mapFrom": "claims.given_name",
          "required": true
        },
        "address": {
          "mapFrom": "claims.address.formatted"
        },
        "picture": {
          "mapFrom": "claims.picture",
          "defaultValue": "http://example.edu/img/placeholder.png"
        },
        "badge": {
          "defaultValue": "http://example.edu/img/badge.png"
        },
        "providerSubjectId": {
          "mapFrom": "authenticationProvider.subjectId"
        }
      },
      "revocable": true,
      "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
      "expiresIn": {
        "years": 1,
        "months": 12,
        "weeks": 52,
        "days": 365,
        "hours": 24,
        "minutes": 1440,
        "seconds": 3600
      }
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Retrieve a Semantic CWT Credential configuration

Retrieve a Semantic CWT credentials configuration

Returns a Semantic CWT credentials configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_RETRIEVE_FAIL
GET/v2/credentials/compact-semantic/configurations/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Unique identifier for the Semantic CWT credentials configuration.

Formatuuid
curl -X GET "https://example.vii.au01.mattr.global/v2/credentials/compact-semantic/configurations/3948c40e-6e19-4ffc-933c-91f643f24264"
{
  "id": "983c0a86-204f-4431-9371-f5a22e506599",
  "type": "CourseCredential",
  "claimMappings": {
    "firstName": {
      "mapFrom": "claims.given_name",
      "required": true
    },
    "address": {
      "mapFrom": "claims.address.formatted"
    },
    "picture": {
      "mapFrom": "claims.picture",
      "defaultValue": "http://example.edu/img/placeholder.png"
    },
    "badge": {
      "defaultValue": "http://example.edu/img/badge.png"
    },
    "providerSubjectId": {
      "mapFrom": "authenticationProvider.subjectId"
    }
  },
  "revocable": true,
  "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  "expiresIn": {
    "years": 1,
    "months": 12,
    "weeks": 52,
    "days": 365,
    "hours": 24,
    "minutes": 1440,
    "seconds": 3600
  }
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Update a Semantic CWT Credential configuration

Update a Semantic CWT credentials configuration

Updates an existing Semantic CWT credentials configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_UPDATE_FAIL
PUT/v2/credentials/compact-semantic/configurations/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Unique identifier for the Semantic CWT credentials configuration.

Formatuuid

Request Body

Update a Credential Configuration

type?unknown

Used to differentiate between different CWT/Semantic CWT credentials configurations on your tenant. Thus, its value must:

  • Be unique across all CWT/Semantic CWT credentials configurations on your tenant.
  • Not be VerifiableCredential.
Length1 <= length <= 1024
claimMappingscredentialConfigurationClaimMappings

This is where you specify how to map claims (user attributes) into issued credentials. Each field in the object corresponds to a claim in the issued credential, and contains one or more from the following attributes:

  • mapFrom: References the path in the user object where the claim is available.
    • When using a URL as a claims namespace identifier, use bracket notation to access the claim value (e.g. mapFrom: "claims['https://example.com/claim-name']").
    • mapFrom is optional when defaultValue is provided, as the latter will be used for all issued credentials. This is referred to as a static claim.
  • defaultValue: Indicates what value is used if required is set to false (field is optional) and no value is provided by the claims source. When defaultValue is provided, mapFrom is optional.
  • required: Indicates whether the claim is required (default: false). When a required claim cannot be retrieved and no defaultValue is available, credential issuance will fail. Example claims object inside the user object
{
  "claims": {
    "given_name": "Jamie",
    "family_name": "Doe",
    "address": {
      "formatted": "116-118 Quay Street, Auckland CBD, Auckland 1010"
    }
  },
  "authenticationProvider": {
    "subjectId": "6d3aab7d-73af-5f61-b47c-109ef6f7558c",
    "url": "https://accounts.google.com"
  }
}

Empty Object

revocable?boolean

When set to true (default), the created credential can later be revoked. When set to false, the credential cannot be revoked.

Defaulttrue
claimSourceId?string

References the unique identifier of a claims source that can be used to retrieve claims and include them in the issued credential.

Formatuuid
expiresIn?object

Used to determine when will issued credentials expire. Can include any combination of years, months, weeks, days, hours, minutes and seconds.

curl -X PUT "https://example.vii.au01.mattr.global/v2/credentials/compact-semantic/configurations/3948c40e-6e19-4ffc-933c-91f643f24264" \  -H "Content-Type: application/json" \  -d '{    "claimMappings": {      "firstName": {        "mapFrom": "claims.given_name",        "required": true      },      "address": {        "mapFrom": "claims.address.formatted"      },      "picture": {        "mapFrom": "claims.picture",        "defaultValue": "http://example.edu/img/placeholder.png"      },      "badge": {        "defaultValue": "http://example.edu/img/badge.png"      },      "providerSubjectId": {        "mapFrom": "authenticationProvider.subjectId"      }    }  }'
{
  "id": "983c0a86-204f-4431-9371-f5a22e506599",
  "type": "CourseCredential",
  "claimMappings": {
    "firstName": {
      "mapFrom": "claims.given_name",
      "required": true
    },
    "address": {
      "mapFrom": "claims.address.formatted"
    },
    "picture": {
      "mapFrom": "claims.picture",
      "defaultValue": "http://example.edu/img/placeholder.png"
    },
    "badge": {
      "defaultValue": "http://example.edu/img/badge.png"
    },
    "providerSubjectId": {
      "mapFrom": "authenticationProvider.subjectId"
    }
  },
  "revocable": true,
  "claimSourceId": "78e1b90c-401d-45bb-89c0-938da4d44c60",
  "expiresIn": {
    "years": 1,
    "months": 12,
    "weeks": 52,
    "days": 365,
    "hours": 24,
    "minutes": 1440,
    "seconds": 3600
  }
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

Delete a Semantic CWT Credential configuration

Delete a Semantic CWT credentials configuration

Deletes an existing Semantic CWT credentials configuration by providing its ID.

Analytic events

  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_START
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_SUCCESS
  • CREDENTIAL_COMPACT_SEMANTIC_CREDENTIAL_CONFIGURATION_DELETE_FAIL
DELETE/v2/credentials/compact-semantic/configurations/{id}

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

idstring

Unique identifier for the Semantic CWT credentials configuration.

Formatuuid
curl -X DELETE "https://example.vii.au01.mattr.global/v2/credentials/compact-semantic/configurations/3948c40e-6e19-4ffc-933c-91f643f24264"
Empty
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}
{
  "code": "string",
  "message": "string",
  "details": [
    {
      "value": "string",
      "msg": "Invalid value",
      "param": "id",
      "location": "body"
    }
  ]
}

How would you rate this page?

CWT Credentials

Previous Page

JSON Credentials

Next Page

On this page

Create a Semantic CWT Credential configurationRetrieve all Semantic CWT Credential configurationsRetrieve a Semantic CWT Credential configurationUpdate a Semantic CWT Credential configurationDelete a Semantic CWT Credential configuration