Skip to content

Authentication & Hostnames

Every JSON resource request requires both the partner-specific hostname and a matching bearer API key.

GET /v1/workspaces HTTP/1.1
Host: <partner-slug>.api.nblick.com
Authorization: Bearer <partner-api-key>
X-External-Actor-Id: operator-42

X-External-Actor-Id is optional. The hostname and Authorization header are required, except when following a signed article image URL returned by the API.

Partner API URL

The production hostname format is:

https://<partner-slug>.api.nblick.com

Use the exact hostname provided by nBlick. A key is valid only on the hostname for the partner to which it was issued. Requests to the bare API hostname or to an unrecognized hostname do not expose White Label API resources.

Bearer API keys

Send the key using the standard authorization header:

Authorization: Bearer nbp_...

A missing, malformed, invalid, inactive, expired, or host-mismatched credential returns:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{
  "detail": {
    "code": "invalid_partner_credentials"
  }
}

Scopes

Every credential contains one or more explicit scopes:

Scope Allows
workspaces:read List and retrieve workspaces
workspaces:write Create or reuse a workspace
reports:read List and retrieve visibility reports
reports:write Launch a visibility report
actions:read List and retrieve actions, poll executions, and retrieve generated outputs
actions:write Launch action executions and generate or replace article images

Scopes do not imply one another. For example, actions:write does not include actions:read, and reports:read does not include workspaces:read.

A valid key without the required scope receives 403 Forbidden:

{
  "detail": {
    "code": "insufficient_scope",
    "required_scope": "actions:read"
  }
}

External actor header

X-External-Actor-Id: operator-42

The value is an optional string of at most 255 characters. It is accepted by authenticated endpoints, is not echoed in response bodies, and never grants access. A longer value returns 422.

Signed article image URLs

Article output responses contain short-lived URLs such as:

https://partner.api.nblick.com/v1/action-executions/aex-P6vB2nQ8rD4kW1yH7cM5t/output/images/0?expires=1788179400&signature=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Fetch this URL exactly as returned. It already carries the authorization needed for that image and does not require the bearer API key. The URL is bound to the partner hostname, execution, image position, current image, and expiration. If it expires or the image is replaced, retrieve the execution output again to obtain a fresh URL.

Interactive API descriptions

The partner hostname exposes /openapi.json, /docs, and /redoc. These documentation routes use HTTP Basic credentials supplied separately by nBlick; the bearer API key does not open them.

Credential handling

  • Keep the API key in a server-side secret store.
  • Do not expose it in browser code or a mobile application.
  • Use a credential with only the scopes needed by the integration component.
  • Treat 401 as a credential or hostname problem that must be corrected before retrying.

See Permissions & Errors for the complete permission matrix and failure responses.