Defining the credential
At the definition stage you will define:
- The name of the credential.
- The schema for the credential.
- The format and structure of the credential - Yoti currently supports, Text (single line), JPEG, PNG and JSON object.
- Who can issue the credential.
- Who can retrieve the credential.
You will need to create the definition, using the Yoti SDK. This is a one-time process which will be used and referenced for every credential issuance.
Once you have added the Yoti SDK dependency to your project, you can use it to build and send your request. See the code snippets below for examples of how to construct the request.
const payload = new Payload({ "name": "com.example.credential", "mimeType": "application/json", "icon": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAIQAACECAYAAhOAFFlC...", "locales": { "default": "en_GB", "values": [ { "locale": "en_GB", "infoUri": "https://www.example.com", "name": "Example Credential Name" } ] }, "authz": { "rules": [ { "name": "REQUEST", "orgs": ["a2399abe-c767-4748-ac37-4b726a9f9150"] }, { "name": "ISSUE", "orgs": ["b3ef4e6d-581e-46e7-a373-7da2a88bc76d"] } ] }});const request = new RequestBuilder() .withBaseUrl('https://api.yoti.com/api/v1/attribute-registry') .withEndpoint('/definitions') .withPemString('PEM_CONTENT') .withHeader('X-Yoti-Auth-Id', 'CLIENT_SDK_ID') .withMethod('POST') .withPayload(payload) .build();const response = await request.execute();| Parameter | Description |
|---|---|
| sdkId | sdkId is the SDK_ID found with your Yoti Hub Application |
| keyPair | The PEM file which is found with your Yoti Hub Application. The PEM file is required to allow the SDK to perform the authentication with the Yoti API. |
Example payload
{ "name": "com.example.company-id", "schema": { "$id": "https://example.com/person.schema.json", "$schema": "http://json-schema.org/draft-07/schema#", "title": "Person", "type": "object", "properties": { "firstName": { "type": "string", "description": "The person's first name." }, "lastName": { "type": "string", "description": "The person's last name." }, "age": { "description": "Age in years which must be equal to or greater than zero.", "type": "integer", "minimum": 0 } } }, "mimeType": "MimeType", "subjectSchema": { "$ref": "#/schema" }, "subjectMimeType": "MimeType", "icon": "data:image/png;base64,iVB...g==", "locales": { "default": "en_GB", "values": [ { "locale": "en_GB", "infoUri": "https://some.website.com/", "name": "example.com identifier" }, { "locale": "it_IT", "name": "Identificativo di example.com" } ] }, "authz": { "rules": [ { "name": "REQUEST" | "ISSUE", "orgs": [ "<UUID>" ], "apps": [ "<UUID>", "<UUID>" ] } ] }}See below for explanation of example payload:
| Parameter | Description | Optional |
|---|---|---|
| Name | This is the name of the credential. This is what will appear on the users Yoti app. | ❌ |
| MimeType | This will declare what type of credential you want. We currently support: text/plain, application/JSON, image/png, image/jpeg. | ❌ |
| Icon | This is the icon that will be presented to a user during the Yoti App share. It will also appear in the sharing receipts. The icon must be at least 112px and smaller than 512kb. | ❌ |
| locales | A list of localisation values. The name will be the display name of the credential. InfoUri is optional and can be pointer to a page that has a description or more information about your credential | ❌ |
| authz | This is where you define who will be allowed to request or issue a credential. This should be in a Yoti SDK ID or Organisation ID. | ❌ |
By supplying the credential in the format of a JSON object, this will allow you to bundle multiple pieces of information together in a single credential request. As an example, you could ask for the credential Employee Number. If this is supplied via a JSON object, within that credential can also contain various other bits of information such as name, email address, access level etc.
Example response
{ "id": "uuid"}