Credentials

4 operations in the Tolvi API, version 1. Paths are relative to https://api.tolvi.co.uk. Every amount is integer pence.

List API credentials

GET/api/v1/credentials

Access: A signed-in Tolvi session only, never an API token.

Firm admins see every personal access token and API client in the firm; everyone else sees their own tokens.

Responses

200 OK, `application/json`

Body: array of ApiCredential.

A personal access token or API client. The secret is never returned again.

200 OK response for GET /api/v1/credentials
Field	Type	Description
`[].id`required	`string (uuid)`
`[].kind`required	`string (CredentialKind)`	One of: `personal`, `client`
`[].name`required	`string`
`[].userId`required	`string (uuid)`nullable	Owner of a personal token.
`[].clientId`required	`string`nullable	Public id of an API client. example "twc_0123456789abcdef01234567"
`[].prefix`required	`string`	First characters of the secret. example "twp_AbCd"
`[].scopes`required	`array of Scope`	One of: `work:read`, `clients:read`, `clients:write`, `engagements:read`, `engagements:write`, `review:write`, `integrations:manage`, `settings:read`, `settings:admin`, `webhooks:manage`, `meetings:read`, `meetings:write`, `client_books:read`, `books:read`, `books:write`, `books:admin`, `self_assessment:read`, `self_assessment:write`, `accounts:read`, `accounts:write`, `corporation_tax:read`, `corporation_tax:write`
`[].role`required	`string (MembershipRole)`nullable	Role ceiling of an API client. One of: `owner`, `admin`, `staff`
`[].staffRole`required	`string (StaffRole)`nullable	One of: `partner`, `manager`, `reviewer`, `preparer`, `admin`
`[].createdAt`required	`string (date-time)`
`[].lastUsedAt`required	`string (date-time)`nullable
`[].expiresAt`required	`string (date-time)`nullable
`[].revokedAt`required	`string (date-time)`nullable

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Create a personal access token

POST/api/v1/credentials/personal

Access: A signed-in Tolvi session only, never an API token.

For scripts and tools acting as you. Scopes are capped by your role, now and whenever it changes.

Request body

Required. application/json: object (CreatePersonalTokenRequest).

Request body for POST /api/v1/credentials/personal
Field	Type	Description
`name`required	`string`	1 to 100 characters
`scopes`required	`array of Scope`	At most what your role allows. One of: `work:read`, `clients:read`, `clients:write`, `engagements:read`, `engagements:write`, `review:write`, `integrations:manage`, `settings:read`, `settings:admin`, `webhooks:manage`, `meetings:read`, `meetings:write`, `client_books:read`, `books:read`, `books:write`, `books:admin`, `self_assessment:read`, `self_assessment:write`, `accounts:read`, `accounts:write`, `corporation_tax:read`, `corporation_tax:write` at least 1 items
`expiresInDays`	`integer`	1 to 366; default 90

Responses

201 Created, `application/json`

Body: object (CreatedCredential).

201 Created response for POST /api/v1/credentials/personal
Field	Type	Description
`credential`required	`object (ApiCredential)`	A personal access token or API client. The secret is never returned again.
`credential.id`required	`string (uuid)`
`credential.kind`required	`string (CredentialKind)`	One of: `personal`, `client`
`credential.name`required	`string`
`credential.userId`required	`string (uuid)`nullable	Owner of a personal token.
`credential.clientId`required	`string`nullable	Public id of an API client. example "twc_0123456789abcdef01234567"
`credential.prefix`required	`string`	First characters of the secret. example "twp_AbCd"
`credential.scopes`required	`array of Scope`	One of: `work:read`, `clients:read`, `clients:write`, `engagements:read`, `engagements:write`, `review:write`, `integrations:manage`, `settings:read`, `settings:admin`, `webhooks:manage`, `meetings:read`, `meetings:write`, `client_books:read`, `books:read`, `books:write`, `books:admin`, `self_assessment:read`, `self_assessment:write`, `accounts:read`, `accounts:write`, `corporation_tax:read`, `corporation_tax:write`
`credential.role`required	`string (MembershipRole)`nullable	Role ceiling of an API client. One of: `owner`, `admin`, `staff`
`credential.staffRole`required	`string (StaffRole)`nullable	One of: `partner`, `manager`, `reviewer`, `preparer`, `admin`
`credential.createdAt`required	`string (date-time)`
`credential.lastUsedAt`required	`string (date-time)`nullable
`credential.expiresAt`required	`string (date-time)`nullable
`credential.revokedAt`required	`string (date-time)`nullable
`secret`required	`string`	The secret. Shown once: store it now.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Create an API client (client credentials)

POST/api/v1/credentials/clients

Role: Firm admin
Access: A signed-in Tolvi session only, never an API token.

For server-to-server integrations. Exchange the client id and secret at POST /api/v1/oauth/token.

Request body

Required. application/json: object (CreateApiClientRequest).

Request body for POST /api/v1/credentials/clients
Field	Type	Description
`name`required	`string`	1 to 100 characters
`scopes`required	`array of Scope`	One of: `work:read`, `clients:read`, `clients:write`, `engagements:read`, `engagements:write`, `review:write`, `integrations:manage`, `settings:read`, `settings:admin`, `webhooks:manage`, `meetings:read`, `meetings:write`, `client_books:read`, `books:read`, `books:write`, `books:admin`, `self_assessment:read`, `self_assessment:write`, `accounts:read`, `accounts:write`, `corporation_tax:read`, `corporation_tax:write` at least 1 items
`staffRole`required	`string (StaffRole)`	Role ceiling for the client; never above your own. One of: `partner`, `manager`, `reviewer`, `preparer`, `admin`

Responses

201 Created, `application/json`

Body: object (CreatedCredential).

The fields are as shown above.

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 429 Too many requests, as problem details (application/problem+json).

Revoke a personal access token or API client

POST/api/v1/credentials/{id}/revoke

Access: A signed-in Tolvi session only, never an API token.

Owners revoke their own tokens; firm admins revoke anything in the firm. Takes effect at once.

Parameters

Parameters for POST /api/v1/credentials/{id}/revoke
Name	In	Type	Description
`id`required	path	`string (uuid)`

Responses

200 OK, `application/json`

Body: object (ApiCredential).

A personal access token or API client. The secret is never returned again.

200 OK response for POST /api/v1/credentials/{id}/revoke
Field	Type	Description
`id`required	`string (uuid)`
`kind`required	`string (CredentialKind)`	One of: `personal`, `client`
`name`required	`string`
`userId`required	`string (uuid)`nullable	Owner of a personal token.
`clientId`required	`string`nullable	Public id of an API client. example "twc_0123456789abcdef01234567"
`prefix`required	`string`	First characters of the secret. example "twp_AbCd"
`scopes`required	`array of Scope`	One of: `work:read`, `clients:read`, `clients:write`, `engagements:read`, `engagements:write`, `review:write`, `integrations:manage`, `settings:read`, `settings:admin`, `webhooks:manage`, `meetings:read`, `meetings:write`, `client_books:read`, `books:read`, `books:write`, `books:admin`, `self_assessment:read`, `self_assessment:write`, `accounts:read`, `accounts:write`, `corporation_tax:read`, `corporation_tax:write`
`role`required	`string (MembershipRole)`nullable	Role ceiling of an API client. One of: `owner`, `admin`, `staff`
`staffRole`required	`string (StaffRole)`nullable	One of: `partner`, `manager`, `reviewer`, `preparer`, `admin`
`createdAt`required	`string (date-time)`
`lastUsedAt`required	`string (date-time)`nullable
`expiresAt`required	`string (date-time)`nullable
`revokedAt`required	`string (date-time)`nullable

Errors: 400 Bad request, 401 Unauthorised, 403 Forbidden, 404 Not found, 429 Too many requests, as problem details (application/problem+json).

Credentials

List API credentials

Responses

200 OK, application/json

Create a personal access token

Request body

Responses

201 Created, application/json

Create an API client (client credentials)

Request body

Responses

201 Created, application/json

Revoke a personal access token or API client

Parameters

Responses

200 OK, application/json

200 OK, `application/json`

201 Created, `application/json`

201 Created, `application/json`

200 OK, `application/json`