# Identity API

> Identity in the Broker & Agent API: check a credential and name its workspace; list the workspaces this connection can reach.

Base URL: `https://workspace.brokerandagent.com/api/public/v1`. Every call needs an [API key or OAuth token](https://brokerandagent.com/developers/api/authentication).

- [Check a credential and name its workspace](#check-a-credential-and-name-its-workspace): `GET /me`
- [List the workspaces this connection can reach](#list-the-workspaces-this-connection-can-reach): `GET /me/workspaces`

## Check a credential and name its workspace

`GET /me`

`plan` is the CRM tier; `website` is the website tier. `access` is what this credential may do, area by area: `off`, `read` or `write` (a credential made before areas existed shows what its scopes amount to).

Scope: `crm.read`

```bash
curl https://workspace.brokerandagent.com/api/public/v1/me \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The workspace this credential answers for. | { `workspace`: object, `plan`: `free`, `pro`, `website`: `none`, `launch`, `growth`, `apiVersion`: `"v1"`, `access`: object } |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

## List the workspaces this connection can reach

`GET /me/workspaces`

A connection can cover several workspaces; name one on each call with the `X-Workspace-Id` header.

Scope: `crm.read`

```bash
curl https://workspace.brokerandagent.com/api/public/v1/me/workspaces \
  -H "Authorization: Bearer bak_YOUR_KEY"
```

**Responses**

| Status | | Returns |
|---|---|---|
| `200` | The one answering now, and every one reachable. | { `current`: string, `workspaces`: array of object } |
| `401` | No credential, or one that's unknown, expired or revoked (unauthorized); or the workspace is suspended (workspace_suspended). |  |
| `403` | The credential lacks the scope (insufficient_scope, naming it in `scope`), the record isn't the person's to change (forbidden), the connection wasn't granted that workspace (workspace_not_granted), or an assistant-only token called outside the assistant's tools (wrong_audience). |  |
| `429` | Too many requests for this credential; wait for Retry-After (rate_limited). |  |

---

Source: https://brokerandagent.com/developers/api/reference/identity
