Skip to main content

Roles and Permissions

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

Permissions#

Admin#

Resources permit access to specific TakeShape 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 in TakeShape, 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 TakeShape token, API Key, or a third-party token.

Evaluation Context#

PropertyDescription
request:headersAll the headers sent with your request
request:queryStringParametersAny query params that came in with the request, parsed as an object. E.g., ?foo=bar could be tested for with request:queryStringParameters:foo
request:ipAddressThe IP address of the client making the API request
claims:providerA special TakeShape claim, identifying the verified provider of these claims
claims:idAnother special TakeShape 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 https://takeshape.io/ namespace. The namespace will be stripped for evaluation purposes. So the custom claim https://takeshape.io/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.