/entityType.setAccessSchema

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 createdidlastUpdated, 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.

The endpoint includes the following methods:

  • POST


POST

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

Authorized Clients

  • owner

Query Parameters

Parameter Type Required Description
type_name string Yes Name of the entityType.
 
for_client_id string Yes Client ID of the client whose access schema is being configured.
 
access_type string Yes Type of access schema being created. Allowed values are:
  • read
  • write
  • read_with_token
  • write_with_token
attributes string Yes JSON 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.