Overview

The Provisionr Workspace API is a RESTful API that allows you to manage your workspace’s directory, policies, integrations, and access controls programmatically.

Base URL

Each workspace has a unique API endpoint based on its workspace identifier.

https://wks{region}{7char}.provisionr.app/api/v1

Replace wks{region}{7char} with your workspace’s unique subdomain.

Request Format

Send request bodies as JSON, and set Content-Type: application/json on any request that includes a body (POST, PUT, and PATCH). Requests without a body, such as GET and DELETE, don’t need it. Responses are always JSON, so an Accept header isn’t required. You’ll see Accept: application/json in the code samples throughout this reference — it’s harmless to include and makes the examples copy-paste ready, but you can safely omit it.

curl https://wksusa1b2c3d.provisionr.app/api/v1/directory/users \
  -H "Authorization: Bearer prv-your-token" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

The example above is a GET request, so neither Content-Type nor Accept is strictly required — only your Authorization header is. Both are shown for consistency with the write examples elsewhere in this reference.

curl https://wksusa1b2c3d.provisionr.app/api/v1/directory/users \
  -H "Authorization: Bearer prv-your-token"

Response Format

All responses are returned as JSON. Successful responses use standard HTTP status codes:

Status Code	Description
`200`	Successful read operation
`201`	Resource created successfully
`202`	Resource updated successfully
`204`	Resource deleted successfully

Error Handling

Every unsuccessful request returns a JSON body — including authentication failures, 404s, and unexpected server errors. The API forces a JSON response on all /api/* routes, so you never receive an HTML error page and your client can parse errors exactly the way it parses successful responses.

Error response structure

All application error bodies share the same envelope:

string

required

A human-readable description of what went wrong, safe to surface to end users. For 500 responses this is intentionally generic — internal details and stack traces are never exposed to clients.

object

Present on validation failures (422) only. Each key is the name of a field that failed validation, and its value is an array of one or more messages describing why.

A minimal error looks like this:

{
    "message": "Unauthenticated."
}

Status codes

The API uses conventional HTTP status codes. A 2xx indicates success (see Response Format); a 4xx means the request needs to change before you retry it; a 5xx or edge error means something failed on our side and the request can usually be retried.

Client errors (4xx)

You should not retry these unchanged — fix the request, credentials, or timing first.

Status	Meaning	How to resolve
`400` Bad Request	The request was malformed — for example, a body that isn’t valid JSON.	Correct the request payload, then retry.
`401` Unauthenticated	The bearer token is missing, expired, or invalid.	Check your `Authorization` header or issue a new token.
`403` Unauthorized	The token is valid but lacks the permission or ability for this operation.	Request a token with the required scope/permission.
`404` Not Found	The route or resource doesn’t exist, or your token isn’t scoped to see it.	Verify the endpoint path and resource ID.
`405` Method Not Allowed	The HTTP method isn’t supported on this endpoint.	Use the method documented for the endpoint.
`409` Conflict	The request conflicts with current state — e.g. creating a resource that already exists.	Reconcile the conflicting state, then retry.
`412` Precondition Failed	A precondition attached to the request wasn’t met.	Re-fetch the current state and retry.
`422` Unprocessable Entity	Validation failed.	Fix the fields listed in `errors` (see Validation errors).
`429` Too Many Requests	You exceeded the rate limit for this endpoint.	Back off and retry (see Rate limiting).

Server errors (5xx)

These indicate a problem on our side. They are safe to retry with exponential backoff.

Status	Meaning	How to resolve
`500` Internal Server Error	An unexpected error. The `message` is generic and the incident is logged automatically on our side.	Retry with backoff; if it persists, report it.
`502` Bad Gateway	The edge received an invalid response from the application, often during a brief deploy or restart.	Transient — retry with backoff.
`503` Service Unavailable	The application is temporarily unavailable or in maintenance.	Transient — retry with backoff.

Edge & network errors (520–530)

These are returned by our edge network (Cloudflare) when it can’t reach the application or doesn’t get a timely response — before your request reaches our code. They’re transient; retry with backoff.

Status	Meaning
`520`	Unknown error at the edge
`521`	Origin refused the connection
`522`	Connection to the origin timed out
`523`	Origin unreachable
`524`	Origin took too long to respond
`525`	SSL handshake with the origin failed
`526`	Invalid origin SSL certificate
`530`	Edge/origin internal error

Edge errors are generated before your request reaches the application, so they may not use the standard { "message": ... } envelope. Match on the HTTP status code rather than parsing the body for these responses.

Validation errors

A 422 response means one or more fields failed validation. The errors object gives you a field-by-field breakdown so you can map each message back to the input that caused it:

{
    "message": "The given data was invalid.",
    "errors": {
        "email": [
            "The email field is required."
        ],
        "role": [
            "The selected role is invalid."
        ]
    }
}

The top-level message is a summary suitable for logs; the per-field arrays in errors are what you’ll want to display next to form inputs.

Rate limiting

Rate limits are applied per token (falling back to your client IP) and vary by endpoint — read endpoints allow far more requests than sensitive operations, and many standard endpoints allow up to 200 requests per minute. Rather than hard-coding a number, treat the response headers as the source of truth. Every response includes your current standing:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed in the current window.
`X-RateLimit-Remaining`	Requests remaining in the current window.

When you exceed the limit, the API responds with 429 Too Many Requests and adds:

Header	Description
`Retry-After`	Number of seconds to wait before retrying.
`X-RateLimit-Reset`	Unix timestamp when the current window resets.

{
    "message": "Too Many Attempts."
}

Honor Retry-After before sending another request. Our official CLI goes a step further — it automatically slows down when X-RateLimit-Remaining drops below 20% and stops before it reaches zero, so bulk jobs don’t trip the limit.

Retrying failed requests

Retry these (with backoff)	Don’t retry unchanged
`429` (after `Retry-After`), `500`, `502`, `503`, `520`–`530`	`400`, `401`, `403`, `404`, `405`, `409`, `412`, `422`

For retryable errors, use exponential backoff with jitter (e.g. 1s, 2s, 4s, 8s…) and cap the number of attempts. For 429, always wait at least the number of seconds given in Retry-After before your next request.

Reporting a problem

If you hit an unexpected error — typically a persistent 500 or edge error — capture enough context for support to trace it. Our official CLI records a Bug Report Metadata block for exactly this purpose; include the equivalent when you open a ticket:

{
    "timestamp": "2026-08-12T18:04:11Z",
    "status": 500,
    "message": "Server Error",
    "errors": {},
    "url": "https://wksusa1b2c3d.provisionr.app/api/v1/directory/users",
    "method": "POST",
    "workspace_id": "...",
    "workspace_user_id": "...",
    "workspace_device_id": "..."
}

The workspace_id, workspace_user_id, and workspace_device_id come from your credentials, not the error response — include whichever your client has on hand along with the timestamp, status, and request url/method.

Getting Started

Endpoints

Base URL

Request Format

Response Format

Error Handling

Error response structure

Status codes

Client errors (4xx)

Server errors (5xx)

Edge & network errors (520–530)

Validation errors

Rate limiting

Retrying failed requests

Reporting a problem

​Base URL

​Request Format

​Response Format

​Error Handling

​Error response structure

​Status codes

​Client errors (4xx)

​Server errors (5xx)

​Edge & network errors (520–530)

​Validation errors

​Rate limiting

​Retrying failed requests

​Reporting a problem

Base URL

Request Format

Response Format

Error Handling

Error response structure

Status codes

Client errors (4xx)

Server errors (5xx)

Edge & network errors (520–530)

Validation errors

Rate limiting

Retrying failed requests

Reporting a problem