Skip to main content

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.



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


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.


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


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

Evaluation context

request:headersAll the headers sent with your request
request:queryStringParametersAny 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:ipAddressThe IP address of the client making the API request
claims:providerA special claim, identifying the verified provider of these claims
claims:idAnother 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:issThe standard JSON Web Token issuer claim.
claims:audThe 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 namespace. The namespace will be stripped for evaluation purposes. So the custom claim will be available as claims:custom:favorite_color.


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": ["", ""]

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.