Skip to content

Authentication

API Guide

The NOB.center API supports two authentication methods:

Method Use case
Bearer token Scripts, CI pipelines, third-party integrations
Session cookie Browser-based access (set automatically on login)

For all programmatic use, bearer tokens are the right choice.

Bearer tokens

Pass an API token in the Authorization header on every request:

Authorization: Bearer nob_<your-token>

Example:

curl -H "Authorization: Bearer nob_abc123xyz..." \
     https://app.nob.center/api/ct-log/filters

Tokens are created and managed in Administration → API Tokens. See API Tokens for how to create one and which permission scopes are available.

Token validation

When the API receives a bearer token it:

  1. Looks up the token by its hash — the raw value is never stored.
  2. Checks the token is not expired and has not been revoked.
  3. Loads the user's role-based permissions for the requested module.
  4. Intersects those permissions with the scopes the token was created with.

The effective permission set is the intersection of what the token explicitly declares and what the owning user's role allows. A token cannot grant permissions the user does not hold.

When you are logged in through the web application, the browser holds a session cookie. API calls made from the browser (or from tools that share the session, such as the Swagger UI at https://app.nob.center/docs) are authenticated via this cookie automatically — no Authorization header is needed.

Session cookie auth is not intended for programmatic use.

Error responses

Status Cause
401 Unauthorized No token or session present, token is expired, or token has been revoked
403 Forbidden Token is valid but the required permission is not in the token's scopes or the user's role

A 403 response body includes a message indicating what was missing:

{"detail": "Missing permission: view_filters in module ct-log"}

How scopes interact with roles

Token scopes are not a separate permission system — they act as a filter on top of the requesting user's existing role permissions.

Example: A user holds the Editor role in DNS Monitoring, which grants create_domains, update_domains, and other write permissions. If their token was created with only dns-watcher:view_domains and dns-watcher:view_records, any write operation will return 403 even though the user's role would otherwise allow it.

This means tokens can always be scoped down to the minimum required for a given integration, without affecting the user's own access in the UI.

See Roles & Permissions for the full list of role-to-permission mappings.