Skip to main content

Configuring Resource Definitions via API

Before you start

Make sure you obtain the following valid parameters from the Helm chart:

  • AS_URI
  • AS_ADMIN_URI
  • AS_ADMIN_STATIC_TOKEN

Further instructions can be found here

Overview

A resource in an FPX network is composed of the following data type (Ordered by the creation time from old to latest)

  1. scope
  2. resource_definition

Type: "scope"

Scopes that clients/resource servers may be allowed to request/provide

AttributeDescriptionExample ValueRequiredLocalizable
nameScope name."Read"YesNo
descriptionDescription of the scope."Allows for read access"NoYes
iconUriExternal link to icon."https://google.ca/img"NoYes

Type: "resource-definition"

Note

The admin api allows scope to be null. In practice, it MUST be valid data

AttributeDescriptionExample ValueRequiredLocalizable
maxPermissionDurationDuration (in milliseconds) that this resource is accessible to a client3000000YesNo
nameReadable (UI Friendly) name of the resource"Identify Profile"YesYes
resourceIdUnique string identifier of the resourceidentity-profile-res-defYesNo
descriptionDescription of the resourceUser identity profile which provides basic information such as emailNoYes
typeExternal reference that describe the resource type. Must be uniquehttps://www.identos.com/resource-definitions/identity-profile-res-defYesNo
iconUriExternal link to icon"https://google.ca/img"NoNo
RelationshipDescriptionRequired
scopeScope previously created. There may be zero scopes.No

Create Resource Definition - All in one

The following request will create two scopes, "read" and "write", and two resource definitions.

curl --location -g --request PATCH '{{AS_ADMIN_URI}}' \
--header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--header 'Accept-Language: en' \
--data-raw '[
{
"op": "add",
"path": "/scope",
"value": {
"type": "scope",
"id": 1,
"attributes": {
"description": "Read value",
"name": "read",
"iconUri": null,
"dType": "Scope"
}
}
},
{
"op": "add",
"path": "/scope",
"value": {
"type": "scope",
"id": 2,
"attributes": {
"description": "write value",
"name": "write",
"iconUri": null,
"dType": "Scope"
}
}
},
{
"op": "add",
"path": "/resource-definition",
"value": {
"type": "resource-definition",
"id": 1,
"attributes": {
"maxPermissionDuration": 3000000000,
"name": "English name",
"resourceId": "identity-profile-res-def",
"type": "https://www.identos.com/resource-definitions/identity-profile-res-def",
"description": "English description"
},
"relationships": {
"scopes": {
"data": [
{
"id": 1,
"type": "scope"
},
{
"id": 2,
"type": "scope"
}
]
}
}
}
},
{
"op": "add",
"path": "/resource-definition",
"value": {
"type": "resource-definition",
"id": "2",
"attributes": {
"maxPermissionDuration": 3000000000,
"name": "Health record english name",
"resourceId": "health-record-res-def",
"type": "https://www.identos.com/resource-definitions/health-record-res-def",
"description": "It is the health record of each individual"
},
"relationships": {
"scopes": {
"data": [
{
"id": 1,
"type": "scope"
},
{
"id": 2,
"type": "scope"
}
]
}
}
}
}
]'

Get Resource Definition

curl --location -g --request GET '{{AS_ADMIN_URI}}/resource-definition/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

Get All Resource Definitions

curl --location -g --request GET '{{AS_ADMIN_URI}}/resource-definition' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

Get Scope

curl --location -g --request GET '{{AS_ADMIN_URI}}/scope/1' \
--header 'Content-Type: application/vnd.api+json' \
--header 'ApiVersion: v1.0' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'Accept-Language: en'

Update Resource Definition - All in one

WARNING

Because Resource Definitions can be integral to defining existing resources, removing Scopes or changing Types can make existing resources unusable or incorrect. Examples of when it might make sense to update these fields for a Resource Definition:

  • The URL defining the specification for this type has been changed.
  • A new Scope is required to onboard a new Resource Server or allow an existing Resource Server to offer more Scopes to Clients.
curl --location -g --request PATCH '{{AS_ADMIN_URI}}' \
--header 'Content-Type: application/vnd.api+json; ext=jsonpatch' \
--header 'Authorization: {{AS_ADMIN_STATIC_TOKEN}}' \
--header 'ApiVersion: v1.0' \
--header 'Accept-Language: en' \
--data-raw '[
{
"op": "replace",
"path": "/scope/1",
"value": {
"type": "scope",
"id": 1,
"attributes": {
"description": "Read value",
"name": "read",
"iconUri": null,
"dType": "Scope"
}
}
},
{
"op": "replace",
"path": "/scope/2",
"value": {
"type": "scope",
"id": 2,
"attributes": {
"description": "write value",
"name": "write",
"iconUri": null,
"dType": "Scope"
}
}
},
{
"op": "replace",
"path": "/resource-definition/1",
"value": {
"type": "resource-definition",
"id": 1,
"attributes": {
"maxPermissionDuration": 3000000000,
"name": "English name",
"resourceId": "identity-profile-res-def",
"type": "https://www.identos.com/resource-definitions/identity-profile-res-def",
"description": "English description"
},
"relationships": {
"scopes": {
"data": [
{
"id": 1,
"type": "scope"
},
{
"id": 2,
"type": "scope"
}
]
}
}
}
},
{
"op": "replace",
"path": "/resource-definition/2",
"value": {
"type": "resource-definition",
"id": 2,
"attributes": {
"maxPermissionDuration": 3000000000,
"name": "Health record english name",
"resourceId": "health-record-res-def",
"type": "https://www.identos.com/resource-definitions/health-record-res-def",
"description": "It is the health record of each individual"
},
"relationships": {
"scopes": {
"data": [
{
"id": 1,
"type": "scope"
},
{
"id": 2,
"type": "scope"
}
]
}
}
}
}
]'

note

The localization feature is covered in more detail here.