Pult Docs

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

  1. Start connecting in the app, for example by adding the MCP server's URL. The app opens Pult in your browser.
  2. Sign in to Pult. If you haven't signed in recently, Pult asks you to sign in again.
  3. 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.
  4. 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 include client_name.
  • Grant types: an app gets authorization_code and refresh_token only. A dynamic registration that asks for another grant type is refused with invalid_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 a client_secret anyway is refused with invalid_client. An app with a client metadata document is always public.
  • Confidential apps: an app that registers dynamically with token_endpoint_auth_method set to client_secret_basic or client_secret_post gets a client_secret in 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_at is 0). Send it in the Authorization header (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 an Origin header, as a browser's does, with invalid_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 resource to say which API the token is for: https://api.pult.com/v1beta/mcp for the MCP server, https://api.pult.com for the REST API. A request without resource gets a token for the REST API. A token works only for the API it was issued for, so an MCP client sends resource=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 scope to get every scope. offline_access is accepted and changes nothing. Pult is not an OpenID Connect provider: a request that names openid or 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 than code) 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 as access_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_token grant 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/revoke ends 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 with invalid_request, and a public app gets 200 while 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 at https://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

On this page