Create an Access Schema

Endpoint URL: {registrationDomain} /entityType.setAccessSchema



Description

Sets the access schema for the specified API client. An access schema defines the subset of attributes to which a client has read or write access. Each client can have one read access schema and one write access schema. Note that access schemas only apply to API-based implementations of the Identity Cloud. If you are using a JavaScript SDK-based implementation then access to forms ands fields is managed by the flow.

Note. if you want to give a client read and write access to the same set of attributes, you must set the read and write schemas in two different calls. For mobile clients, you should use the read_with_token and write_with_token settings.


Defining the attributes parameter

When granting permissions to a top-level attribute in the schema, use the attribute name formatted in JSON. Example: 

["aboutMe","created"]

When granting permissions to an attribute that is part of a larger object, use an attribute path. The attribute path begins at the root of the schema, and uses dots to navigate from the plurals to the target sub attribute. For example, to refer to the city attribute in the primaryAddress plural, use:

["/primaryAddress.city"]

When setting an access_type you must include all attributes in one call. If an attribute is not specified, the access_type is removed.

Try to avoid including the attributes created, id, lastUpdated, and uuid when configuring the schema. Including these reserved attributes in the attributes list can result in "Unexpected internal error" messages.

Refer to the Registration Error Codes section for details on error codes.


Respects the API Client Allow List: Yes


API Client Permissions

The following table indicates the API clients that can (and the API clients that can't) be used to call this endpoint:

owner
access_issuer
direct_access
direct_read_access
login_client
Yes
No
No
No
No


Authentication

This endpoint supports both Basic authentication (recommended) and janrain-signed authentication.

How to Create an Authentication String


Base URL

The base URL for this endpoint is your Identity Cloud Capture domain; for example:

https://educationcenter.us-dev.janraincapture.com

Your Capture domains (also known as Registration domains) can be found in the Console on the Manage Application page:

Examples

Example 1

This command gives read-only user profile access to the API client with the client ID 7890fghi7890fghi. To assign read-only access, the access_type is set to write and the attributes parameter is set to an empty array ([]). That's translated as “Don’t give write access to any of the attributes in the user entity type.”


curl -X POST \
  -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg" \
  --data-urlencode type_name=user \
  --data-urlencode for_client_id=7890fghi7890fghi \
  --data-urlencode access_type=write \
  --data-urlencode attributes='[]' \
  https://my-app.janraincapture.com/entityType.setAccessSchema
          

      Running this command in Postman


Example 1 Response


{
  "schema": {
    "attr_defs": [
      {
        "name": "id",
        "description": "simple identifier for this entity",
        "type": "id"
      },
      {
        "name": "uuid",
        "description": "globally unique identifier for this entity",
        "type": "uuid"
      },
      {
        "name": "created",
        "description": "when this entity was created",
        "type": "dateTime"
      },
      {
        "name": "lastUpdated",
        "description": "when this entity was last updated",
        "type": "dateTime"
      }
    ],
    "name": "user"
  },
  "notice": "reserved attributes (id, uuid, created, lastUpdated) are automatically included in the access schema",
  "stat": "ok"
}


Example 2

The following command gives the API client 0987fghi0987fghi write access to the givenName and familyName attributes in the user entity type.


curl -X POST \
  -H "Authorization: Basic c2dueXZ1czZwYzRqbTdraHIybmVxNWdzODlnYnIyZXE6d3Q0YzN1bjl3a2tjZnZ5a25xeDQ0eW5jNDc2YWZzNjg"\
  --data-urlencode type_name=user \
  --data-urlencode for_client_id=7890fghi7890fghi \
  --data-urlencode access_type=write \
  --data-urlencode attributes='["givenName", "familyName"]'\
  https://my-app.janraincapture.com/entityType.setAccessSchema
          

      Running this command in Postman


Example 2 Response


{
  "schema": {
    "attr_defs": [
      {
        "name": "id",
        "description": "simple identifier for this entity",
        "type": "id"
      },
      {
        "name": "uuid",
        "description": "globally unique identifier for this entity",
        "type": "uuid"
      },
      {
        "name": "created",
        "description": "when this entity was created",
        "type": "dateTime"
      },
      {
        "name": "lastUpdated",
        "description": "when this entity was last updated",
        "type": "dateTime"
      },
      {
        "length": 1000,
        "constraints": [
          "unicode-printable"
        ],
        "name": "familyName",
        "type": "string",
        "case-sensitive": false
      },
      {
        "length": 1000,
        "constraints": [
          "unicode-printable"
        ],
        "name": "givenName",
        "type": "string",
        "case-sensitive": false
      }
    ],
    "name": "user"
  },
  "notice": "reserved attributes (id, uuid, created, lastUpdated) are automatically included in the access schema",
  "stat": "ok"
}
          


Query Parameters

ParameterTypeRequiredDescription
type_namestringYesName of the entityType.
 
for_client_idstringYesClient ID of the client whose access schema is being configured.
 
access_typestringYesType of access schema being created. Allowed values are:
  • read
  • write
  • read_with_token
  • write_with_token
attributesstringYesJSON list of attribute names. These names can be full attribute paths. If a path terminates at an object or plural, then that means that the client will have access to all sub-attributes. Whenever possible, avoid including the reserved attributes created, id, lastUpdated, and uuid in your list of attributes.