# Authentication

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

Source: https://developer.prosaic.works/docs/getting-started/authentication

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](/docs/getting-started/quickstart#1-create-an-api-key) 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-node';

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](/docs/apps/oauth-apps) covers registering an app, the full flow, and the review policy for apps connected to many workspaces. The [Node SDK](/docs/sdk/node#oauth) has helpers for PKCE, token exchange and refresh.

## Errors you may see

| Status | When                                                                                                                                                                  |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | No credential, or one that is invalid, expired or deleted.                                                                                                            |
| `403`  | Not 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`). |
| `404`  | The 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.
