Guides Reference

Authentication overview

Every call to the CyberSentriq API carries an OAuth 2.0 access token in an Authorization: Bearer header. This guide covers the two ways to get a token, and the facts that stay the same whichever you pick.

The examples across these guides use the URLs, audience and client ID of this environment: the one you are reading them on. Read them on the environment you are integrating against.

Which path do you need?

There are two ways in. Pick by who is calling.

Path Use it when Guide
User / device-code A person signs in: a native or desktop app acting on a person's behalf. User and device-code authentication
Service account (M2M) A backend runs unattended, with no human present. Service account and M2M authentication

Both end the same way: you hold an access token, and you send it as Authorization: Bearer <ACCESS_TOKEN> to the API.

Facts common to both paths

Fact Value
Issuer https://auth.cybersentriq.com/ (note the trailing slash)
Token endpoint https://auth.cybersentriq.com/oauth/token
JWKS (public keys) https://auth.cybersentriq.com/.well-known/jwks.json
Token audience (aud) https://api.cybersentriq.com
API base URL (what you call) https://api.cybersentriq.com
Signing algorithm RS256
Auth header Authorization: Bearer <ACCESS_TOKEN>
API version ?api-version= query parameter (omit to get the default)
Permissions Your effective set, in the https://cybersentriq.com/permissions claim — see Permissions

The token audience is simply the API base URL: request a token for https://api.cybersentriq.com, and send that same token to https://api.cybersentriq.com when you call the API.

How a token is checked

The API validates every token the same way. Any client that inspects a token should do the same four checks:

  • Signature against the tenant JWKS, using RS256.
  • Issuer (iss) equals https://auth.cybersentriq.com/.
  • Audience (aud) equals https://api.cybersentriq.com.
  • Expiry (exp) is in the future.

The token is a standard RS256 JWT. Alongside sub, aud, iss, exp and scope, it carries sid, org_id and azp, plus CyberSentriq namespaced claims (see below).

Where permissions come from

Authorization is resolved from your org and role and carried in a claim:

  • https://cybersentriq.com/permissions is the authoritative set of effective permissions. Read this claim to decide what the caller may do.
  • Ignore the native flat permissions array. It is empty for federated org-member logins. Always use https://cybersentriq.com/permissions.

Scopes and least privilege

Request the scopes your integration needs when you authenticate, on every login path. A token then carries only the intersection of the scopes you request and the permissions your role grants, so you hold a least-privilege token rather than your full authority. An empty scope request is refused: name your scopes, and request full_access explicitly if you genuinely need your whole permission set.

Scope enforcement is rolling out. Until it lands, a token still carries your full role-derived permission set regardless of the scopes you request, so do not yet rely on scopes to constrain a token. Request the right scopes now so your integration is correct when enforcement arrives, and protect every token as full authority in the meantime.

The token also carries CyberSentriq namespaced claims. Most integrations only need permissions above, but you may also see:

  • https://cybersentriq.com/oid: the caller's CyberSentriq organization ID (the org_... identifier). This is the org the token is scoped to.
  • https://cybersentriq.com/roles: the caller's CyberSentriq roles (for example account-admin, authenticated-user). Roles are what the permissions set above is resolved from.
  • https://cybersentriq.com/mfa_at: ISO 8601 timestamp of the caller's most recent multi-factor authentication.
  • https://cybersentriq.com/mfa_max_age: how long, in seconds, that MFA stays valid before the API requires a step-up re-authentication. Compare it against mfa_at.
  • https://titanhq.com/uid: the caller's TitanHQ user ID (the TitanHQ service identity titan_uid).
  • https://titanhq.com/oid: the caller's TitanHQ organization UUID (from the organization's directory metadata).
  • https://titanhq.com/roles: the caller's TitanHQ roles.
  • https://redstor.com/uid: the caller's RedApp user ID (the RedApp service identity redapp_uid, a UserGuid).
  • https://redstor.com/oid: the caller's RedApp company ID.

The titanhq.com/* and redstor.com/* claims are present only when the caller has an identity in that product, so a given token may carry some and not others. They are transitional, per-product claims that are subject to change. Do not rely on them. Build integrations against the https://cybersentriq.com/* claims instead, with https://cybersentriq.com/permissions as the authoritative authorization signal.

This environment

These guides are served per environment, and each instance shows only its own values. The environment you are reading them on uses:

API base URL Auth issuer
https://api.cybersentriq.com https://auth.cybersentriq.com/

The same guides are published on each environment as it opens up; read them there to get that environment's values.

Next