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. Includes creating profiles via assessment invite. Allows:

Creating new profiles (sends a real assessment invite email or SMS)
Updating profile metadata
Deleting profiles
Resending invite links

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)

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

Which Authentication Method Should I Use?

Security Notes

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

​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

Which Authentication Method Should I Use?

Security Notes