Roles and permissions

Roles allow you to allow access to the administrative features, API queries, API mutations and data. The permissions affect what a user will be able to do and see in the API, and in the admin UI.

Permissions

Admin

Resources permit access to specific admin and admin-related functionality. You can restrict access to billing, project creation, and other similar activities.

tip

Sometimes API activity will require underlying resource permissions to work. For instance, if you'd like to allow access to a mutation like createProfile which creates a Profile entry, it may also require Workflow and Workflow Step permissions.

API

The API section allows you to provide access to your GraphQL API at a granular level. You can provide access to the various Queries and Mutations that comprise your API, as well as to the Shapes and shape fields.

For a given query to succeed the underlying shape will also need to be provided for the role. For instance, if I give access to the getProfile query I should also allow access to the corresponding Profile shape.

Conditions

Conditions establish rules for the assignment of the role's permissions to a request. They are useful in cases where you'd like to provide access to your API for users authenticated by a third-party, like Auth0. Conditions are written using the AWS JSON Policy syntax, and are evaluated against the request context and authenticated claims.

tip

Conditions will only be evaluated on requests valid authentication included — either a token, API Key, or a third-party token.

Evaluation context

Property	Description
request:headers	All the headers sent with your request
request:queryStringParameters	Any query params that came in with the request, parsed as an object. For example, ?foo=bar could be tested for with request:queryStringParameters:foo
request:ipAddress	The IP address of the client making the API request
claims:provider	A special claim, identifying the verified provider of these claims
claims:id	Another special claim, an id for the request as determined by an individual auth provider's implementation. For instance, with the Auth0 provider this will be the same as the verified sub claim.
claims:iss	The standard JSON Web Token issuer claim.
claims:aud	The standard JSON Web Token audience claim. aud and iss are required for third-party JWT verification and will always be present.
claims:*	Any valid JWT claim allowed to exist at the root of the token.
claims:custom:*	Any custom, namespaced claim using the https://example.com/ namespace. The namespace will be stripped for evaluation purposes. So the custom claim https://example.com/favorite_color will be available as claims:custom:favorite_color.

Examples

Applying the role to a request authenticated by Auth0.

{
  "StringEquals": {
    "claims:provider": "auth0"
  }
}

Applying the role to a request authenticated by Auth0, with the profile scope included.

{
  "ForAllValues:StringEquals": {
    "claims:provider": "auth0"
  },
  "ForAllValues:StringLike": {
    "claims:scope": "\bprofile\b"
  }
}

Applying the role to a request based on IP addresses — you can use an array to allow multiple, and you can use ranges.

{
  "IpAddress": {
    "request:ipAddress": ["1.1.1.1", "127.0.0.1/24"]
  }
}

Import / Export

Custom roles will be exported with your project info. They can also be authored and imported with patterns. See the patterns docs for more.