All requests to Privacy Bee’s API require the use of OAuth 2.

All authentication is user-level, and any access to any tenant (business-level) resources will require the user to have appropriate roles configured. For example, a consumer or basic employee account can access their own information, however an employee with the “Business Admin” role assigned will have full access to all resources of that business. If the authenticated user has permissions over more than one company (multiple linked business emails or through a multi-tenant business). Each company will have their own base URL that includes a company ID that can be found on the OAuth API Keys page.

Authentication tokens are short lived unless chosen specifically to last longer so if you are using the Client Credentials flow you want to check the expires_in parameter of the bearer token to determine if you need to request a new token first. If you are using Authorization Code flow you can use the refresh token in order to get a new access token.

Supported Grant Type Flows:

• Authorization Code Flow with PKCE
  • Use Case: Manual Resource Owner Access (ex: the Buzz app, our browser extension, Vendor & Cookie Consent)
  • Supports Authorization header with bearer tokens (JWT)
• Client Credentials Flow
  • Use Case: Backend services, CLI, scheduled access, etc.
  • Requires a Client ID and Client Secret (your Privacy Bee API Key)

Authorization Header

This is the easiest and default recommended way to interact with Privacy Bee’s V3 API. To get started, simply navigate to your organization’s “Developer API” app within Privacy Bee:

Click the blue “Generate OAuth 2 Client” button in the top right corner, then select the “Client Credentials” toggle and flip on the “Generate Long-Lived Token“:

This will create an Authorization Token that lasts forever, allowing you to immediately start passing the “Authorization” header to API requests without any further authentication or token management.

curl https://api.privacybee.com/ -H "Authorization: Bearer ${ACCESS_TOKEN}" 

Client Credentials

Client Credentials are the ideal way for machine-to-machine interactions with our API. They allow you to quickly get an authentication token to interact with our API programmatically. There are two ways of generating tokens. When you create the client on the app, you will have the option to choose Long-Lived Token. If you decide to be long-lived, you will be immediately given a bearer token without expiration. You do not need to use the following endpoints to generate new tokens.

If you do not choose Long-Lived Token (more secure), you will use the following endpoint. When you create the client, you will be given a secret. With the client_id and client_secret, you can make requests to the following endpoint to generate new access tokens.

---

POST /oauth/token

Parameters: The following parameters must be included in the body of the request

Variable	Data Type	Required	Description
grant_type	string	Yes	Must be set to “client_credentials” per RFC 6749.
client_id	string	Yes	Client ID is displayed on your API Keys page
client_secret	string	Yes	Client secret that was generated when you created the client ID

Example Request

curl -X POST https://api.privacybee.com/oauth/token \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Return:

Variable	Data Type	Description
token_type	string	Bearer
expires_in	string	When will the token expire
access_token	string	The bearer token you can use to interact with the API and make authenticated requests

Note: All requests need to have the Header "Authorization": "Bearer ACCESS_TOKEN"

---

Authorization Code

GET /oauth/authorize

This is the first step of authenticating a Resource Owner, usually via a browser login (retrieving a multi-factor PIN, SSO, SAML, OIDC, or similar)

Parameters:

Variable	Data Type	Required	Description
response_type	string	Yes	Must be set to “code” per RFC 6749.
client_id	string	No	Client ID is displayed on your API Keys page.
redirect_uri	string	No	The URL to send the users in the event of successful authentication. https:// only. This must be approved for your client ID
state	string	No	A unique string to be passed through to the request_uri on successful authentication, used to validate requests and prevent CSRF attacks. It must be 40-120 characters
challenge	string		A base 64 encoded SHA256 encryption of the state

Return: Returns the following values, either encoded in the redirect_uri as path segments via an HTTP/302 redirect, or returned as a JSON object via an HTTP/200 (if no request_uri was specified)

Field	Data Type	Description
client_id	string	Passed through ID from the request
code	string	A single-use authorization code that expires 300 seconds after generation, used to exchange for an access token
state	string	Passed through state variable from the request. Confirm the values match exactly to ensure no interception or manipulation has occurred
error	enum	If anything goes wrong during the authorization, the error variable will be returned with one of the following values: invalid_request, unauthorized_client, access_denied, unsupported_response_type, server_error, or temporarily_unavailable (per RFC 6749 4.1.2.1)
error_description	string	If anything goes wrong during the authorization, this human-readable description will be populated

---

POST /oauth/token

Get an access token using the code returned from /oauth/authorize

Parameters:

Variable	Data Type	Required	Description
grant_type	string	Yes	"authorization_code"
response_type	string	Yes	"code"
client_id	string	Yes	OAuth Client ID
redirect_url	string	Yes	Must match redirect URI of the client ID
code_verifier	string	Yes	See RFC 7636 specification, this is the code that was used to generate the challenge in the /oauth/authorize step
code	string	Yes	Authorization code returned in the first step

Return:

Variable	Data Type	Description
token_type	string	"Bearer"
expires_in	integer	Time until the access_token expires
access_token	string	Access token to be used in requests
refresh_token	string	Can be used to get a new refresh token

---

POST /oauth/token

You can also use this same endpoint to refresh tokens.

Variable	Data Type	Required	Description
grant_type	string	Yes	"refresh_token"
refresh_token	string	Yes	The refresh token
client_id	string	Yes	OAuth Client ID

Return:

Variable	Data Type	Description
token_type	string	“Bearer"
expires_in	integer	Time until the access_token expires
access_token	string	Access token to be used in requests
refresh_token	string	Can be used to get a new refresh token