Protect your API

Authentication proves a person or service identity. Authorization determines whether it can perform the particular operation. Enforce that decision in your API, alongside your product’s own data rules.

Configure the resource and grants

Create an API resource in API Access with a stable audience such as https://api.example.test/billing and explicit permission keys such as invoices:read and invoices:write. Grant only the required subset to the selected application client.

For a human client, also define the corresponding application permissions under Roles & permissions, create a role containing them, and assign it to the user in the intended context. API permission keys and role permission keys must agree. Admission to an application is separate from that role assignment.

For human tokens requested with a resource, the effective permission set must satisfy all relevant authority: workspace/application policy, active client/API grant, requested scopes, active user and session, and the user’s role permissions in context. The API grant is a ceiling, not an automatic role. For M2M, authority comes from the client credential and explicit service API grant; user roles do not apply.

Request your API by including one resource in authorization or the M2M token request. The identifier is audience selection, not a redirect or an arbitrary URL to fetch. Its exact value must match the registered API and client grant. This use follows the resource-selection model of RFC 8707; the current implementation supports one selected resource per request.

Check each protected action

Send the incoming opaque access token from your API server to Oathvera:

POST <issuer>/authorization/check
Authorization: Bearer <access-token>
Content-Type: application/json

{"resource":"https://api.example.test/billing","permission":"invoices:read","organization_id":null}

Use the resource and permission configured by your API handler. Do not let the caller choose a weaker permission, a different issuer or another organization’s data context. Oathvera derives the token’s subject, tenant and application; do not add your own user_id or application_id to the request.

A human grant can produce:

{
  "allowed": true,
  "decision_id": "<decision-reference>",
  "reason": "PERMISSION_GRANTED",
  "policy_version": 3
}

An authenticated request without the required grant can return HTTP 200 with allowed: false. Invalid tokens and operational failures use non-success responses. Permit work only for HTTP 200 and the JSON boolean allowed: true. A timeout, malformed body, rate limit, unavailable service or missing field must not allow access. The local helper demonstrates this behavior with bounded requests and no redirects.

Workload responses identify their principal type, client, application and tenant. They do not currently include the human response’s decision ID/policy-version fields. Avoid requiring one response shape for both principal types.

Organization context

Application-wide role assignments are evaluated with organization_id: null. Organization-scoped assignments require that exact organization and active membership. They do not inherit an application-wide assignment simply because the user has one. Required enterprise SSO must also match the session’s organization context.

Derive the organization from the protected record or a validated application context, then check that context with Oathvera. Do not accept an arbitrary organization supplied by the caller without checking which data it owns. M2M currently supports organization_id: null only; service-specific restrictions on customer records belong in your API’s business rules.

Revocation and operation

Check at the point of access and do not cache an allow decision across requests. Role, membership, session, client and API-grant changes can remove authority before a token’s five-minute expiration. A cryptographically valid ID token is not evidence of current API permission.

Oathvera’s permission check does not filter your database or decide ownership of a particular invoice. Enforce record ownership, application business rules and transactional consistency yourself. An allowed decision is not a lock on subsequent policy changes; for a long-running or delayed operation, obtain a fresh decision at execution time.

Do not use /oauth2/introspect as a replacement for action authorization. It is a confidential client’s own-token activity check, not a general cross-client resource-server validation service.

Requests are server-to-server: no Origin, no query parameters, exactly the three JSON fields above, and a body no larger than 2 KiB. Rate limits and errors are summarized in the HTTP reference. Log action, outcome and available decision reference without logging access tokens or credentials.