Creating your first OAuth Token

In this section we are going to show you how to get secure access to Fides' API. Fides' API supports the OAuth2 Client Credentials Grant which requires to you create a Client ID and Secret with a specified set of scopes.

If you are self-deploying and not using Fides Cloud (opens in a new tab), you might recall that you created a Root OAuth Client ID and Client Secret, however, like any good security oriented company, we strongly recommend you do not use Root credentials for day-to-day tasks. Use the Root Credentials to create a new Client ID/Secret pair with limited scopes using the endpoint below.

If you are using Fides Cloud, reach out to your Customer Success Manager and they will provide the initial OAuth token to create additional tokens.

Loading latest documentation...

Steps

Using POST /api/v1/oauth/token, pass in the Root Client ID and Secret with the appropriate scopes requested to get your intial Access Token. As this is a standard OAuth Client Credentials flow, your API tool probably already supports an Oauth flow already - but if not, you'll need to submit an application/x-www-form-urlencoded request with query params grant_type=client_credentials, client_id={{Root Client ID}}, and client_secret={{Root Client Secret}}. For example:
Example 'POST /api/v1/oauth/token' Request
```
curl -X 'POST' \
'https://{{Fides Server Hostname}}/api/v1/oauth/token' \
-H 'accept: application/json' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id={{Root Client ID}}&client_secret={{Root Client Secret}}'
```
- NOTE: Using the Swagger Docs hosted on your Fides server /docs you can input these Root Client Credentials using the "Authorize" button in the top right corner of the page!
Using this Access Token as the Bearer Token (if you are not using Swagger), make a request to POST /api/v1/client to create your new Client that will be used to access the APIs on a day-to-day basis.
Example 'POST /api/v1/client' Response
```
{
    "client_id": "{{ newly generated Client ID }}",
    "client_secret": "{{ newly generated Client Secret }}"
}
```

We now need to assign scopes to this new Client. First, you can query the API for the full list of available scopes using GET /api/v1/oauth/scope. For example:

Example 'GET /api/v1/oauth/scope' Response

[
    "allow_list:create",
    "allow_list:delete",
    "allow_list:read",
    "allow_list:update",
    "classify_instance:create",
    "classify_instance:read",
    "classify_instance:update",
    "cli-objects:create",
    "cli-objects:delete",
    "cli-objects:read",
    "cli-objects:update",
    "client:create",
    "client:delete",
    "client:read",
    "client:update",
    "config:read",
    "config:update",
    "connection:authorize",
    "connection:create_or_update",
    "connection:delete",
    "connection:instantiate",
    "connection:read",
    "connection_type:read",
    "connector_template:register",
    "consent:read",
    "consent_settings:read",
    "consent_settings:update",
    "consent_webhook:post",
    "consent_webhook_token:create",
    "ctl_dataset:create",
    "ctl_dataset:delete",
    "ctl_dataset:read",
    "ctl_dataset:update",
    "ctl_policy:create",
    "ctl_policy:delete",
    "ctl_policy:read",
    "ctl_policy:update",
    "current-privacy-preference:read",
    "custom_asset:update",
    "custom_field:create",
    "custom_field:delete",
    "custom_field:read",
    "custom_field:update",
    "custom_field_definition:create",
    "custom_field_definition:delete",
    "custom_field_definition:read",
    "custom_field_definition:update",
    "custom_report:create",
    "custom_report:delete",
    "custom_report:read",
    "data_category:create",
    "data_category:delete",
    "data_category:read",
    "data_category:update",
    "data_subject:create",
    "data_subject:delete",
    "data_subject:read",
    "data_subject:update",
    "data_use:create",
    "data_use:delete",
    "data_use:read",
    "data_use:update",
    "database:reset",
    "datamap:read",
    "dataset:create_or_update",
    "dataset:delete",
    "dataset:read",
    "dataset:test",
    "discovery_monitor:read",
    "discovery_monitor:update",
    "encryption:exec",
    "endpoint_cache:update",
    "evaluation:create",
    "evaluation:delete",
    "evaluation:read",
    "evaluation:update",
    "fides_cloud_config:read",
    "fides_cloud_config:update",
    "fides_taxonomy:update",
    "generate:exec",
    "gvl:update",
    "language:read",
    "location:read",
    "location:update",
    "masking:exec",
    "masking:read",
    "messaging-template:update",
    "messaging:create_or_update",
    "messaging:delete",
    "messaging:read",
    "openid_provider:create",
    "openid_provider:delete",
    "openid_provider:read",
    "openid_provider:update",
    "organization:create",
    "organization:delete",
    "organization:read",
    "organization:update",
    "policy:create_or_update",
    "policy:delete",
    "policy:read",
    "privacy-experience:create",
    "privacy-experience:read",
    "privacy-experience:update",
    "privacy-notice:create",
    "privacy-notice:read",
    "privacy-notice:update",
    "privacy-preference-history:read",
    "privacy-request-access-results:read",
    "privacy-request-notifications:create_or_update",
    "privacy-request-notifications:read",
    "privacy-request:create",
    "privacy-request:delete",
    "privacy-request:read",
    "privacy-request:resume",
    "privacy-request:review",
    "privacy-request:transfer",
    "privacy-request:upload_data",
    "privacy-request:view_data",
    "privacy_center_config:read",
    "privacy_center_config:update",
    "privacy_preferences:create",
    "property:create",
    "property:delete",
    "property:read",
    "property:update",
    "rule:create_or_update",
    "rule:delete",
    "rule:read",
    "saas_config:create_or_update",
    "saas_config:delete",
    "saas_config:read",
    "scope:read",
    "storage:create_or_update",
    "storage:delete",
    "storage:read",
    "system:create",
    "system:delete",
    "system:read",
    "system:update",
    "system_history:read",
    "system_manager:delete",
    "system_manager:read",
    "system_manager:update",
    "system_scan:create",
    "system_scan:read",
    "taxonomy:create",
    "taxonomy:delete",
    "taxonomy:update",
    "tcf_publisher_override:read",
    "tcf_publisher_override:update",
    "user-permission:assign_owners",
    "user-permission:create",
    "user-permission:read",
    "user-permission:update",
    "user:create",
    "user:delete",
    "user:password-reset",
    "user:read",
    "user:update",
    "validate:exec",
    "webhook:create_or_update",
    "webhook:delete",
    "webhook:read"
]

Lastly, you assign the desired scopes to your Client with PUT /api/v1/oauth/client/{client_id}/scope. Below is a sample payload to authorize just the /privacy-experience, /privacy-notice, and privacy-preference APIs - depending on your application, you'll want to provide more or less scopes as needed:
Example 'PUT /api/v1/oauth/client/{client_id}/scope' Request
```
[
    "privacy-experience:create",
    "privacy-experience:read",
    "privacy-experience:update",
    "privacy-notice:create",
    "privacy-notice:read",
    "privacy-notice:update",
    "privacy-preference-history:read",
    "privacy_preferences:create",
]
```
We are now ready to use this new Client ID and Secret pair to execute requests against the Fides API.

Authenticating access_manual_webhook