Create workspace API credential

POST

/v1/api-credentials

const url = 'https://api.dockt.com/v1/api-credentials';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"display_name":"example","description":"example","credential_type":"api_key","allowed_scopes":["account:read"],"expires_at":"2026-08-06T09:30:00Z"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.dockt.com/v1/api-credentials \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "display_name": "example", "description": "example", "credential_type": "api_key", "allowed_scopes": [ "account:read" ], "expires_at": "2026-08-06T09:30:00Z" }'

Creates a machine credential for the active workspace. The returned secret is shown once and cannot be retrieved later.

Authorizations

bearerAuth
sessionCookie

Parameters

Header Parameters

idempotency-key

minLength(1)

Caller-generated retry key for duplicate-sensitive create and resend operations. Keys are scoped to the authenticated principal, method, and route and are retained for 24 hours.

string

>= 1 characters

Caller-generated retry key for duplicate-sensitive create and resend operations. Keys are scoped to the authenticated principal, method, and route and are retained for 24 hours.

Request Body^required

application/json

Creates a machine credential scoped to the active workspace.

object

display_name

required

maxLength(120)

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

description

string

credential_type

Credential mechanism. Defaults to api_key when omitted.

string

Allowed values: api_key m2m

allowed_scopes

Permissions granted to the credential. Values must match the target scope type; omitting or sending an empty list applies Dockt’s current least-privilege defaults for that scope.

Array<string>

Allowed values: account:read account:write workspaces:read workspaces:write api-credentials:read api-credentials:manage features:read features:write social-compliance-packages:read workspace:read webhooks:manage assessments:read assessments:write documents:read documents:create documents:delete decisions:read decisions:outcome

expires_at

Optional API-key expiration timestamp. Omit to use the identity provider default. M2M access tokens are short-lived and refreshed through client credentials instead.

string format: date-time

Responses

201

Envelope for a single resource response.

application/json

Envelope for a single resource response.

object

object

required

string

Allowed values: single

data

required

Newly created credential with one-time secret material included in the response.

object

object

required

string

Allowed values: api_credential

required

Unique Dockt API credential identifier.

string

/^cred_[A-Za-z0-9_]+$/

account_id

required

Any of:

string
null

Unique Dockt account identifier.

string

/^acc_[A-Za-z0-9_]+$/

workspace_id

required

Any of:

string
null

Unique Dockt workspace identifier.

string

/^wsp_[A-Za-z0-9_]+$/

display_name

required

maxLength(120)

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

description

required

Any of:

string
null

string

credential_type

required

Credential format. API keys are bearer secrets; machine-to-machine credentials use a client credential exchange.

string

Allowed values: api_key m2m

scope_type

required

Whether the credential acts across an account or only within one workspace.

string

Allowed values: account workspace

client_id

required

Any of:

minLength(1)
null

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

token_url

required

Any of:

string
null

Absolute HTTP or HTTPS URI.

string format: uri

api_key_hint

required

Any of:

minLength(1)
null

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

allowed_scopes

required

Array<string>

enabled

required

boolean

last_used_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

created_at

required

ISO 8601 date-time string.

string format: date-time

updated_at

required

ISO 8601 date-time string.

string format: date-time

client_secret

required

Any of:

minLength(1)
null

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

api_key

required

Any of:

minLength(1)
null

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

Example

{
  "object": "single",
  "data": {
    "object": "api_credential",
    "account_id": "acc_example",
    "workspace_id": "wsp_example",
    "credential_type": "api_key",
    "scope_type": "account",
    "token_url": "https://example.com/webhooks/dockt",
    "allowed_scopes": [
      "account:read"
    ],
    "last_used_at": "2026-08-06T09:30:00Z",
    "created_at": "2026-08-06T09:30:00Z",
    "updated_at": "2026-08-06T09:30:00Z"
  }
}

400

The request did not match the expected schema

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/invalid-request",
  "title": "Bad request",
  "status": 400,
  "detail": "The request did not match the expected schema.",
  "instance": "req_example1042"
}

401

Problem Details response for HTTP 401. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/missing-auth",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Send a valid bearer token or browser session.",
  "instance": "req_example1042"
}

403

Problem Details response for HTTP 403. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The authenticated principal does not have the required permission.",
  "instance": "req_example1042"
}

404

Problem Details response for HTTP 404. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource was not found in the authenticated scope.",
  "instance": "req_example1042"
}

409

Problem Details response for HTTP 409. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The request conflicts with the current resource state.",
  "instance": "req_example1042"
}

422

Problem Details response for HTTP 422. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "Correct the invalid fields and send the request again.",
  "instance": "req_example1042",
  "errors": {
    "issues": [
      {
        "path": [
          "body",
          "worker",
          "nationality"
        ],
        "message": "Expected a two-letter country code."
      }
    ]
  }
}

429

Problem Details response for HTTP 429. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "detail": "Wait for the Retry-After interval before retrying.",
  "instance": "req_example1042"
}

500

Problem Details response for HTTP 500. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/internal",
  "title": "Internal server error",
  "status": 500,
  "detail": "Retry the request safely or contact Dockt support with the request ID.",
  "instance": "req_example1042"
}

Create workspace API credential

Authorizations

Parameters

Header Parameters

Request Body required

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

500

Example

Request Body^required