Authentication

Authenticate securely to the Profile API using Access Tokens. We support two modern strategies:

Machine-to-Machine (M2M) for your own backend services
OAuth 2.1 for any integration that acts on behalf of a user: third-party apps, AI agents, dashboards

Machine-to-Machine (M2M) Authentication

M2M authentication is designed for backend services, internal automations, and server-to-server integrations. It uses access tokens that are scoped to your organization and expire automatically.

How It Works

Request an Access Token Exchange your client_id and client_secret for an access token. Credentials can be supplied either in the request body or as HTTP Basic Auth:

POST https://vanguard.profilebehavior.com/api/v4/auth
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}

Or, equivalently, with Basic Auth:

POST https://vanguard.profilebehavior.com/api/v4/auth
Authorization: Basic base64(client_id:client_secret)

Response:

{
  "access_token": "eyJhbGciOi...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Include the Token in API Requests Add the access token to the Authorization header:
Authorization: Bearer YOUR_ACCESS_TOKEN
Tokens Expire Access tokens are short-lived and expire after approximately 1 hour. Request a new one when the previous token is near expiry.

Example (cURL)

curl --request POST \
  --url https://vanguard.profilebehavior.com/api/v4/test \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"ping": "pong"}'

OAuth 2.1 Authentication

OAuth 2.1 is for integrations that act on behalf of a specific Profile user. That covers third-party apps, AI agents and MCP servers, CLI tools, and any browser-based dashboard where a user signs in. Tokens issued under OAuth are scoped to one Profile account (the one the user consented from) and carry OAuth scopes that narrow what the integration can do. The same bearer token works against the REST API (/api/v4/*) and the MCP endpoint (/mcp).

Discovery

Fetch the OAuth protected-resource metadata to learn where the authorization server lives and what scopes exist:

GET /.well-known/oauth-protected-resource HTTP/1.1
Host: vanguard.profilebehavior.com

{
  "resource": "https://vanguard.profilebehavior.com",
  "authorization_servers": ["https://login.profilebehavior.com"],
  "scopes_supported": [
    "profiles:read",
    "profiles:write",
    "tags:manage",
    "account:read",
    "account:write"
  ],
  "bearer_methods_supported": ["header"]
}

On any 401 from a protected endpoint, the response includes a WWW-Authenticate: Bearer resource_metadata="..." header pointing at this document, so clients can discover it automatically.

Client Registration

You have two ways to register an OAuth client:

Pre-registered integrations. For a production integration you build or operate (your own dashboard, an internal tool, a specific third-party connector), contact support to register a client and receive a client_id (and client_secret for confidential clients).
Dynamic Client Registration (DCR). MCP agents and other on-the-fly clients can register themselves at the authorization server’s DCR endpoint. See the authorization server’s discovery document at https://login.profilebehavior.com/.well-known/oauth-authorization-server for the registration URL. No pre-provisioning required.

How It Works

Redirect to authorize Send the user’s browser to the authorization endpoint with the standard OAuth 2.1 query params (client_id, redirect_uri, response_type=code, scope, state, code_challenge, code_challenge_method=S256):
https://login.profilebehavior.com/oauth/authorize?client_id=...&redirect_uri=...&response_type=code&scope=profiles:read+tags:manage&state=...&code_challenge=...&code_challenge_method=S256
Consent Profile shows the user a branded consent screen listing your app, the account they’re connecting, and the scopes requested. On approval, Profile redirects the browser back to your redirect_uri with an authorization code.

Token exchange Exchange the code for an access token at the token endpoint:

POST https://login.profilebehavior.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...

Make API requests Include the token as a bearer in the Authorization header:
Authorization: Bearer USER_ACCESS_TOKEN

Scopes

Scopes are the unit of authorization for OAuth tokens. A token can only perform operations covered by the scopes the user granted. Users see and can deny each scope on the consent screen, and can revoke an entire connection at any time from the Connected apps section of their user profile. Request only the scopes your integration actually needs. Over-asking on the consent screen is the single most common reason users deny a connection.

`profiles:read`

Read access to profiles and their behavioral data. Allows:

Listing profiles on the connected account
Reading a profile’s name, email, and phone
Reading DISC, Focus, and Core assessment scores
Reading AI-generated behavioral debriefs (and triggering generation of a debrief if one doesn’t exist yet)

Does not allow: creating, modifying, or deleting profiles; accessing profiles on accounts the user isn’t signed in to. Typical use: any integration that summarizes or analyzes behavioral data, including AI assistants answering questions about people on the team.

`profiles:write`

Full profile lifecycle, including creating profiles and delivering assessment invites. Allows:

Creating new profiles (no invite is sent until you call an invite endpoint)
Updating profile metadata
Deleting profiles
Sending assessment invites by email or SMS, or retrieving a direct assessment link

Does not allow: reading behavioral scores (request profiles:read alongside if you need both). Typical use: HR tools, onboarding automations, roster-management integrations.

`tags:manage`

Full CRUD on tags and tag membership. Allows:

Listing, creating, renaming, recoloring, and deleting tags
Replacing the set of profiles attached to a tag

Does not allow: creating or modifying profiles. The profiles a tag references must already exist on the account. Typical use: cohort-management, group-assignment, and filtering workflows.

`account:read`

Read access to account-level metadata. Allows:

Reading account name, logo, and preferences
Reading the assessment catalog
Reading resource aliases (external ID mappings)

Does not allow: reading profiles or behavioral data (that’s profiles:read). Typical use: diagnostic and reporting tools that need context about the account they’re connected to.

`account:write`

Modify account-level settings. Allows:

Updating account logo and preferences
Creating, updating, and deleting resource aliases

Does not allow: deleting the account, changing billing, or modifying users. Typical use: integrations that need to keep resource-alias mappings in sync with an external system.

Scope enforcement

Every API request is validated against the token’s granted scopes before the handler runs. An OAuth client calling an endpoint without the corresponding scope receives a 403 with a descriptive error message. There is no silent degradation or partial success.

Example OAuth Request

GET /api/v4/account HTTP/1.1
Host: vanguard.profilebehavior.com
Authorization: Bearer eyJhbGciOi... (access token)

Regions

Every account has a Home Region: the United States, the European Union, or Singapore. An account’s data is stored and served only in its Home Region, and each region has its own API host.

Region	Base URL
Default	`https://vanguard.profilebehavior.com/api/v4`
United States	`https://vanguard-us.profilebehavior.com/api/v4`
European Union	`https://vanguard-eu.profilebehavior.com/api/v4`
Singapore	`https://vanguard-sea.profilebehavior.com/api/v4`

Use the base URL for your account’s Home Region. The default host routes each request to the nearest region, which is correct for most callers most of the time, but it is not guaranteed to be your account’s region.

The 421 response

If a request reaches a region that does not hold your account, the API does not process it. It responds with 421 Misdirected Request and tells you where to go:

{
  "status": "error",
  "code": 421,
  "error": {
    "message": "This account is served from another region",
    "timestamp": "2025-01-01T09:42:52.329056-05:00"
  },
  "region": {
    "zone": "EU",
    "apiUrl": "https://vanguard-eu.profilebehavior.com/api"
  }
}

The same values are returned in the X-Profile-Region and X-Profile-Region-Url headers. To handle it, replace the host in your base URL with the host from region.apiUrl, keep the /v4 path, and send the request again. Any endpoint that requires authentication can return 421. Once you are talking to the right region you will not see it again for that account, so it is safe to remember the region and use it for every later request.

API keys and regions

An API key belongs to the account that created it, and that account belongs to one region. Using a key against another region’s host returns 421 with the correct region. Keys created before regional hosting was introduced return 404 Not Found from the wrong region instead of 421. If you see that, switch to your account’s regional base URL.

Which Authentication Method Should I Use?

Use Case	Auth Type
Your own backend services talking to our API	✅ M2M
Cron jobs & internal automation	✅ M2M
Third-party apps acting on a user’s behalf	✅ OAuth
AI agents and MCP servers (ChatGPT, Claude)	✅ OAuth
User-facing apps where a person signs in	✅ OAuth

Security Notes

Never expose client secrets in frontend apps or browser-based code. Public clients (browser, mobile, CLI) must use PKCE instead.
Access tokens are short-lived (~1 hour). Use refresh tokens to obtain new access tokens without re-prompting the user.
OAuth users authenticate through Profile’s secure login. Passwords are never shared with external tools.
Users can view and revoke any connected app from the Connected apps section of their user profile at any time.

API Documentation

Endpoints

Account

Assessment

Assessment Invite

Fixtures

Playbook AI

Profile

Resource Alias

Tag

Machine-to-Machine (M2M) Authentication

How It Works

Example (cURL)

OAuth 2.1 Authentication

Discovery

Client Registration

How It Works

Scopes

`profiles:read`

`profiles:write`

`tags:manage`

`account:read`

`account:write`

Scope enforcement

Example OAuth Request

Regions

The 421 response

API keys and regions

Which Authentication Method Should I Use?

Security Notes

​Machine-to-Machine (M2M) Authentication

​How It Works

​Example (cURL)

​OAuth 2.1 Authentication

​Discovery

​Client Registration

​How It Works

​Scopes

​profiles:read

​profiles:write

​tags:manage

​account:read

​account:write

​Scope enforcement

​Example OAuth Request

​Regions

​The 421 response

​API keys and regions

​Which Authentication Method Should I Use?

​Security Notes

Machine-to-Machine (M2M) Authentication

How It Works

Example (cURL)

OAuth 2.1 Authentication

Discovery

Client Registration

How It Works

Scopes

`profiles:read`

`profiles:write`

`tags:manage`

`account:read`

`account:write`

Scope enforcement

Example OAuth Request

Regions

The 421 response

API keys and regions

Which Authentication Method Should I Use?

Security Notes