Authentication

Authenticate your user when using the API

The API uses personal access tokens to authenticate requests.

You can view and manage your access tokens in the Developer Settings of your user account.

Bearer Authentication

API requests are authenticated using the Bearer Auth scheme.

To authenticate a request, provide the token in the Authorization header of the request.

Access tokens are tied to the user account for which they were created. A token provides the same level of access and permissions privileges that its associated user account would have in the user interface.

Most API endpoints support both Bearer authentication and Cookie authentication.

Secure cookie authentication may be preferred in some specific integration scenarios. For example, if you are using the platform in headless mode, and if you are building your own user interface with a library such as React, then you might prefer cookies over bearer tokens for authenticating HTTP requests that originate with your (authenticated) users.

Authentication cookies incorporate several security features to protect user data and prevent unauthorized access. These security features include the following:

  • The Secure flag ensures the cookie is only transmitted over encrypted HTTPS connections, preventing interception during communication between clients and the server.

  • The HttpOnly attribute prevents client-side scripts from accessing the cookie through JavaScript, mitigating cross-site scripting (XSS) attacks.

  • The SameSite attribute helps prevent cross-site request forgery (CSRF) attacks by restricting the cookie to same-site contexts or explicitly allowing cross-site usage.

  • An expiration date limits the cookie's lifespan.

  • Domain and path restrictions limit where the cookie can be used and where it can be accessed.

  • The cookie value is signed with a cryptographically secure digital signature, and then encrypted for additional privacy and security.

Client Secret Authentication

A small number of specific API endpoints support Client Secret authentication.

An OAuth 2.0 client secret is not a fixed format, but rather a string of characters, typically a long, randomly generated sequence. It's a confidential credential that is known to (and shared by) your application and the server .

A typical client secret might look like this: "wJalrXUtnFEMI0O6JX5MCkmbs6JqPcx3"

Every developer account is assigned a client secret that is generated by the system. You can see the client secret assigned to your account on the My Profile page, in the section titled Developer Settings.

To authenticate a request, provide the secret in the Authorization header of the request. Please note the header value must include the word Secret as a prefix. For example:

Secret wJalrXUtnFEMI0O6JX5MCkmbs6JqPcx3

Client secrets are generated using cryptographically strong random number generators, ensuring they have sufficient entropy to resist brute-force attacks and are statistically unique across different client applications.

  • The secrets are typically long, random strings that are computationally infeasible to guess or derive through cryptanalysis.

  • The secrets are designed to be treated as sensitive credentials with proper lifecycle management, including secure generation, storage, rotation, and revocation capabilities.

Client secret authentication is limited in scope because it requires the ability to securely store and protect the secret, which is feasible only for confidential clients like server-side applications. Bearer tokens have more sophisticated security features (e.g., shorter lifespans, scoped permissions, easy revocation) — this is why bearer authentication is preferred and required for most API endpoints throughout the platform.

Last updated

Was this helpful?