Authenticate with OAuth
When you invoke a fidesops API, you must pass an access token as the value of the
Authorization header. Furthermore, the token must include a scope that gives you permission to take an action on the API. For example, let's say you want to create a new Policy by calling
PATCH /api/v1/policy. The token that you pass to the
Authorization header must include the
This document explains how to craft a properly-scoped access token.
Create the root client
The fidesops Postman collection includes several example requests to assist in set up and configuration.
First, create an access token for the "root" client, included in the deployment by default. The root client's token is all-powerful: It contains all scopes, so it can call any of the fidesops APIs.
To create the root token, you pass the
OAUTH_ROOT_CLIENT_SECRET environment variables (which are automatically defined in your system) to the
POST /api/v1/oauth/token endpoint. You also set the
grant_type parameter to
1 2 3 4 5
You'll notice that there's no
Authorization header. This is the only fidesops API that doesn't require an access token.
token call is successful, the response will return the root client's access token in the
1 2 3 4 5 6 7
Create additional clients
Because the root client's token is all-powerful, it can create new clients and new client ID/client secret pairs which can be used to create additional access tokens.
For general best practices, we recommend creating a client with scope
CLIENT_CREATE to create any new clients. This will help to reduce the utilization of the all-scopes root client.
To create the client ID/secret pair, call
1 2 3 4 5
For this call, we have to populate the
Authorization header. Notice that the header's value is formed as
Bearer <token>. We also have to declare the request's
Content-Type to be
Authorize a client with scopes
To add scopes to the client, the body of your request must contain an array of scope tokens.
If the call is successful, Fidesapi responds with a new client ID/client secret pair:
1 2 3 4 5 6 7
Create an access token
You then create a new access token by calling
POST /api/v1/oauth/token with the new credentials.
In the above example, your new access token only lets the client read policies and rules -- the client cannot create other clients, write policies, or perform other operations using fidesops APIs.
Access token expiration
By default, access tokens expire after 11520 minutes (8 days). To specify a different expiration time (in minutes) set the
OAUTH_ACCESS_TOKEN_EXPIRE_MINUTES environment variable.
If you call a fidesops API with an expired token, the call returns
Other OAuth Calls
Fidesops defines OAuth operations that let you delete a client, and read and write a client's scopes. See the OAuth section of the API documentation for details.