Back to Docs

Authentication

API keys, OAuth 2.1 with PKCE, choosing a workspace, and keeping credentials safe.

Every request to https://app.prosaic.works/api/public/v1 carries a credential. There are two kinds:

  • API keys, for your own server-side integration. This is what an embedded ledger uses.
  • OAuth access tokens, for an app that other Prosaic users connect to their own workspaces.

Both are sent the same way, and both act as a Prosaic user.

API keys

Workspace owners and admins create keys in the Prosaic app: Settings → Users, then the user's Actions menu (⋯), then Manage API keys. The quickstart has the steps. A key starts with prsk_, is shown once when it is created, and has an expiry date. The same dialog lists a user's keys and deletes them.

Send the key as a bearer token:

bash
curl https://app.prosaic.works/api/public/v1/me \
  -H "Authorization: Bearer prsk_..."

An x-api-key: prsk_... header is accepted too. The SDK uses the bearer form:

ts
import Prosaic from '@prosaic/sdk';

const prosaic = new Prosaic(process.env.PROSAIC_API_KEY!);

What a key can reach

A key acts as the user it was created for. It can reach every workspace that user belongs to, and within a workspace it sees what their role allows:

  • Workspace owners and admins see every entity in the workspace.
  • Advisors see only the entities they have been given access to.
  • Client and standard user roles cannot use the API with a key.

Creating entities needs an owner, admin or advisor role. Journals and other changes made with the key are recorded against its user. For an integration, consider a dedicated user so its activity is easy to tell apart from a person's.

An entity the key cannot see returns 404, not 403, so the API does not reveal that it exists.

Choosing a workspace

A user can belong to several workspaces. Each request acts in one of them:

  1. The workspace named in the x-workspace-id header, if you send one. If the user is not a member of it, the request fails with 403 and Not a member of requested workspace.
  2. Otherwise, the workspace the user last switched to in the app, or their first workspace if they are no longer in that one.

GET /me lists the user's workspaces and their IDs. With the SDK, set workspaceId on the client or on a single call:

ts
const prosaic = new Prosaic(apiKey, { workspaceId: 'YOUR_WORKSPACE_ID' });

const { data: me } = await prosaic.me.retrieve({
  workspaceId: 'ANOTHER_WORKSPACE_ID',
});

Choosing a workspace never widens what the user can do. Send x-workspace-id whenever the user is in more than one workspace, so a change of workspace in the app cannot redirect your integration.

OAuth 2.1 with PKCE

Use OAuth when your app acts for other Prosaic users, such as accountants connecting their firm's workspace to your product. Prosaic uses the authorization-code flow with PKCE, and the code challenge must use S256.

  • Scopes: openid, profile, email, and offline_access to receive a refresh token.
  • Lifetimes: access tokens last 24 hours; refresh tokens last 30 days.
  • Discovery: https://app.prosaic.works/.well-known/oauth-authorization-server

An access token is sent exactly like an API key, Authorization: Bearer ..., and acts as the user who approved your app, with that user's access. Workspace selection works the same way.

OAuth apps covers registering an app, the full flow, and the review policy for apps connected to many workspaces. The Node SDK has helpers for PKCE, token exchange and refresh.

Errors you may see

StatusWhen
401No credential, or one that is invalid, expired or deleted.
403Not a member of the workspace in x-workspace-id; the workspace's trial has expired (TRIAL_EXPIRED); or the user has a client role (CLIENT_API_ACCESS_DISABLED).
404The entity does not exist, or the credential cannot see it.

Keep credentials on your server

  • Keep API keys and OAuth client secrets out of browser bundles, mobile apps and source control. Load them from your server's environment or a secrets manager.
  • Call Prosaic from your backend, never directly from a user's browser.
  • Use HTTPS. The SDK refuses a non-HTTPS baseUrl unless it is a loopback address for local development.
  • Rotate keys before they expire: create the new key, deploy it, then delete the old one.
  • Keep validation details from error responses out of public logs; they can contain accounting data.