Authentication
How API keys and OAuth connections work, what each can read, and why a request is refused.
The API accepts two credentials, both sent in the Authorization header:
- an API key, which an admin creates for an integration;
- an OAuth access token, which an app gets when a person connects it to their Pult account (see Connect with OAuth).
Send the key
A request with an API key sends it in the Authorization header:
Authorization: Bearer pult_<key>Keys start with pult_ and are 54 characters long. The API accepts them only in this header, never
in the URL.
Manage keys
Organization admins manage keys in the Pult Dashboard under Settings → Security → API keys.
- Create: the key is shown once, when you create it. Afterwards the dashboard shows only its first 12 characters, so you can recognize it.
- Expiry: every key expires, at most two years after it was created. Shorter lifetimes limit the damage if a key leaks.
- Revoke: any admin can revoke any key of the organization. A revoked key stops working at once.
- Replace a key: create a new key, switch your integration to it, then revoke the old one. Your integration keeps running throughout.
What a key can read
A key reads with its owner's rights. Only admins can create keys, so every key sees what an admin sees in the dashboard's reports. Your organization's privacy settings apply as they apply to admins.
Each endpoint needs a scope: users:read, groups:read, offices:read, bookings:read,
presence:read or visitors:read. A key gets every scope that exists when it is created. A scope
added later never reaches an existing key: create a new key to use it. For example, visitors:read
was added on 2026-11-05, so a key created before then can't read visits.
Bookings need Pult Workplace, offices need Pult Workplace or Pult Visitors, the presence endpoints
need Pult Presence, and visits need Pult Visitors. Without the product, these endpoints answer
403 feature_not_enabled.
Paused keys
A key can be paused. It works again on its own as soon as the reason no longer holds. The Pult Dashboard shows each key's status and, for a paused key, the reason.
Connect with OAuth
Apps such as Claude and ChatGPT connect to Pult with OAuth. A person signs in to Pult and approves
the app, and the app then reads with that person's rights. Nobody copies a key into the app. Pult's
authorization server is https://auth.pult.com.
Who can connect
For now, only admins can connect apps, and only when their organization has API access (see Getting started). A connection reads with the rights of its owner, the person who approved it, so it sees what an admin sees in the dashboard's reports. It holds the scopes its owner approved, and each endpoint needs the same scope and product as with a key (see What a key can read).
Approve a connection
- Start connecting in the app, for example by adding the MCP server's URL. The app opens Pult in your browser.
- Sign in to Pult. If you haven't signed in recently, Pult asks you to sign in again.
- Check the request. Pult shows the name the app gave itself (not verified by Pult), where the app comes from when Pult knows it, where the access goes, the account and organization it will act as, and what it can read. Approve only if you just started connecting this app yourself.
- Click Approve or Deny. You approve or deny the request as a whole.
Pult then sends you an email about the new connection.
Manage connections
- Your connections: in the Pult web app, the Connections section of Settings lists the apps connected to your account.
- Your organization's connections: admins see every connection and its owner in the Pult Dashboard under Settings → Security → Connections.
- Revoke: you can revoke your own connections, and any admin can revoke any connection of the organization. A revoked connection stops working at once. To use the app again, connect it again.
- Valid until: a connection ends after 90 days unused, on the date the lists show as Valid until.
- Paused: while a connection's owner is not an admin, the connection is paused and the API
answers
403 connection_paused. It works again once its owner is an admin again. - Archived users: archiving a user revokes their connections. Unarchiving the user doesn't bring them back.
For app developers
Pult publishes everything an app needs in its server metadata,
https://auth.pult.com/.well-known/oauth-authorization-server. MCP clients find it through the MCP
server's 401 challenge.
- Registration: an app registers itself. Its client ID is the URL of its client metadata
document (Client ID Metadata Documents), or it registers dynamically (RFC 7591) at
https://auth.pult.com/oauth/register. Pult has no form for registering apps. Pult may remove a dynamic registration that never connected an account: an app whose client ID Pult no longer knows gets an error page and has to register again. A client metadata document must includeclient_name. - Grant types: an app gets
authorization_codeandrefresh_tokenonly. A dynamic registration that asks for another grant type is refused withinvalid_client_metadata. A client metadata document that lists others keeps only these two. - Public apps: an app that registers with
token_endpoint_auth_method: none, or names no method, sends no client secret. A public app that sends aclient_secretanyway is refused withinvalid_client. An app with a client metadata document is always public. - Confidential apps: an app that registers dynamically with
token_endpoint_auth_methodset toclient_secret_basicorclient_secret_postgets aclient_secretin the registration response. Pult shows it only this once and keeps no readable copy, so an app that loses it registers again. It never expires (client_secret_expires_atis0). Send it in theAuthorizationheader (client_secret_basic) or in the form (client_secret_post): Pult accepts either, whatever method you registered with, at the token and revocation endpoints. Keep it on your server: Pult refuses a confidential app's request that carries anOriginheader, as a browser's does, withinvalid_request. - PKCE: every authorization uses PKCE with
S256. - Redirect URIs: HTTPS or a loopback address, matched exactly. An app whose redirect URIs are all loopback addresses may use any port.
- Resource: send
resourceto say which API the token is for:https://api.pult.com/v1beta/mcpfor the MCP server,https://api.pult.comfor the REST API. A request withoutresourcegets a token for the REST API. A token works only for the API it was issued for, so an MCP client sendsresource=https://api.pult.com/v1beta/mcp, as current MCP clients do. - Scopes: request one or more of the scopes in What a key can read, or
send no
scopeto get every scope.offline_accessis accepted and changes nothing. Pult is not an OpenID Connect provider: a request that namesopenidor any other scope is refused before the person sees it. - Refused authorization requests: a request Pult refuses before the person signs in and decides
(for example a missing PKCE challenge, an unknown scope or resource,
prompt=none, or a response type other thancode) shows Pult's error page. Pult never sends these errors to the app's redirect URI, so check the request your app builds. Once the person has signed in and decided, a denial goes back to the app asaccess_denied. - Access tokens: an access token is valid for one hour. Send it as
Authorization: Bearer <token>. - Refresh tokens: Pult issues a refresh token when the app's registration includes the
refresh_tokengrant type (grant_types). Without one, the app has to connect again when its access token expires. Each refresh returns a new refresh token: use it for the next refresh. Sending a spent refresh token again can end the connection. - Revocation: revoking a token at
https://auth.pult.com/oauth/revokeends the whole connection. A confidential app authenticates there as it does at the token endpoint. An app can revoke only its own tokens: a confidential app that sends another app's token is refused withinvalid_request, and a public app gets200while the token stays valid. - Protected resource metadata: the MCP server's is at
https://api.pult.com/.well-known/oauth-protected-resource/v1beta/mcp. For an app configured by hand, the REST API's is athttps://api.pult.com/.well-known/oauth-protected-resource.
The 401 challenge
A 401 carries a WWW-Authenticate header:
- MCP server:
Bearer resource_metadata="https://api.pult.com/.well-known/oauth-protected-resource/v1beta/mcp", which leads an MCP client to Pult's authorization server. When the request sent a bearer token that was refused, the header adds, error="invalid_token". - REST API:
Bearer error="invalid_token".
Refusals
A refused request answers 401 or 403 with a code that names the reason. The
error catalogue lists every code and what to do.
A bearer value that starts with pult_ is checked as an API key, and any other as an OAuth access
token. So a key sent without its prefix, or with quotes around it, gets 401 invalid_token. A
request without any credential gets 401 invalid_api_key.
Last updated on