The bynh API.

Authentication

Send a personal API token as a bearer token on every request. Create one in the app under My account → API tokens; see Create an API token. The whole token, {id}|bynh_pat_…, goes in the header.

Authorization: Bearer 42|bynh_pat_••••••••

Every path starts with https://api.bynh.io/api/v1/workspaces/{workspace}, where {workspace} is your workspace’s address. A token works only in the workspace it was made in; any other workspace answers 404. Tokens expire after 7, 30 or 90 days or a year, and a missing, expired or revoked token gets 401.

Scopes and roles

A token has one of two scopes, and acts with its owner’s current role in the workspace.

Errors

Errors are JSON with a message that says what went wrong, in the token owner’s language. Validation errors (422) add errors, with the messages for each field.

{
  "message": "Enter the standard, like ISO/IEC 27001:2022. (and 1 more error)",
  "errors": {
    "name": ["Enter the standard, like ISO/IEC 27001:2022."],
    "issuer": ["Enter who issued it, like BSI Group."]
  }
}

Editing pauses when a trial ends without a plan or a payment doesn’t go through. Reads keep working; writes answer 403 with a message such as “Your trial has ended, so editing is paused. Your trust center stays online.”

Rate limits

Each person can make 120 requests a minute, shared by all their tokens and their browser session. Every response tells you where you stand.

Some actions have their own, lower limit on top, shown on each endpoint: uploads (20 a minute), evidence changes (60 a minute), reminders (30 an hour), monitor checks (10 a minute), incident notices (30 an hour), invitations (60 an hour) and subprocessor changes (90 a minute). Their 429 has a message but no Retry-After; wait a minute and try again.

Pagination

Most lists return every row in data, in one response. Three are different:

Conventions

• Successful responses wrap their payload in data. DELETE answers 204 with no body. Downloads return the file.
• Ids are numbers. Frameworks use their slug (iso-27001) and disclosure reports their number in your workspace.
• Dates are YYYY-MM-DD; times are ISO 8601 in UTC.
• Messages and labels follow the token owner’s language, English or Arabic. Values such as statuses never change.
• Every change is recorded in your workspace’s audit log, with the token’s owner as the person who made it.
• There are no outgoing webhooks. To react to changes, read the lists on a schedule, or connect Slack in the app.

Endpoints