Skip to main content



TakeShape has three mechanisms for authorization and authentication:

  • Personal Access Token - Used for development, this allows access to anything the user has permissions for. Users are assigned a role per project that they are a member of (owner, admin, editor, viewer, custom).
  • API Key - Used for backend integration, CI or anonymous access from the frontend. API keys are assigned a role that specifies permissions for a single project.
  • JWT - Support for Auth0 and OpenID Connect. Roles are assigned based on custom conditional logic on the claims of the token. This allows users to connect directly to TakeShape from the frontend without the need for a proxy.

Authorization is granted through the use of a bearer token. You will need to pass an Authorization header and use the Bearer prefix.


Authorization: Bearer <token>


TakeShape roles are defined by an access policy and assignment conditions.

Access Policy

A role’s access policy can be defined using the web client or in a JSON format similar to AWS IAM. Every part of the user-facing GraphQL API and management APIs are specified as resources with defined actions. Roles are part of our reusable project pattern and can be imported/exported. Here is an example of the anonymous role for our Penny e-commerce starter kit:

Role editor UI:

Example JSON Policy:


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. These conditions are stored with the role and can be edited in the UI or imported via a pattern.

In this screenshot we are assigning the authenticated role to requests that have a valid OpenID Connect token:

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"

See more examples in our Roles and Permissions docs

Example Auth0 JWT Flow

Still need help? Get in touch with us.