Create an access schema

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're using a JavaScript SDK-based implementation then access to forms and fields is managed by the flow.

📘

If you want to give a client read and write access to the same set of attributes, you need to set the read and write schemas in two different calls. For mobile clients, 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 names in a JSON array. For example:

["aboutMe","created"]

When granting permissions to an attribute that's 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 main attribute to the target sub attribute. For example, to refer to the city attribute in the primaryAddress plural, use this syntax:

["primaryAddress.city"]

When setting an access_type you must include all attributes in youe call. If an attribute isn't specified, the access schema isn't applied to that attribute.

Avoid using 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 page for details on error codes.

API client permissions

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

Authentication

This operation supports both Basic authentication (recommended) and janrain-signed authentication. See Get started for more information.

Base URL

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

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

Your Capture domain (also known as a Registration domain) can be found in Console on the Manage Application page.

Examples

Example 1: Assign a read-only access schema

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

Example 1 response

If your API call succeeds the response contains information about all the attributes in the access schema:

{
  "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: Assign a read-write access schema

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

Example 2 response

If your API call succeeds the response contains information about all the attributes in the access schema:

{
  "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"
}

Parameters

All parameters need to be configured as x-www-form-urlencoded body parameters.