Introduction

When requesting a token using any of the available authentication classes, you can request scopes with your token. Scopes are a way to allow only certain tokens to have certain permissions. You can set various scope levels on an endpoint to match scope levels on the token.

Scopes should be space delimited and should be passed as a scope parameter.

Specifying Resource Scopes

We can now specify scopes in our resource:

from entry.api.Resource import Resource
from entry.api.JsonSerialize import JsonSerialize
from entry.api.auth import EncryptedTokenAuthentication
from app.User import User
class UserResource(Resource, JsonSerialize, EncryptedTokenAuthentication):
model = User
scopes = ['user:read']

Awesome! Now any token that doesn't have a user:read scope attached to their token will see an error message saying their token is not correctly authenticated with the right scopes.

We can add multiple scopes as well. In this case the API will only be accessible if the user has all of the permission scopes.

from entry.api.Resource import Resource
from entry.api.JsonSerialize import JsonSerialize
from entry.api.auth import EncryptedTokenAuthentication
from app.User import User
class UserResource(Resource, JsonSerialize, EncryptedTokenAuthentication):
model = User
scopes = ['user:read', 'user:companies']

Now the API will be only accessible to users who have a token with BOTH the user:read and the user:companies scopes. You can use this to create really advanced permission access to your resources.

Know that you are not limited in what your scopes are named. For the purposes of this documentation, we stick with a standard like resource:action but you can have scopes that look like user.read or user::read

Unauthorized Scope Access

Some users may request an API endpoint that they do not have access to. In this instance, a 401 Unauthorized status code is sent back along with an error messaging detailing why the request was rejected.