Authorization for api.document.m7.org

The Document API accepts M7 access tokens and resolves each accepted identity to an active local principal. A valid token identifies the caller; the principal's role and ownership rules determine which resources the caller may use.

The API base URL is:

https://api.document.m7.org

Supported credential

Credential	Format	Public transport	Where it applies
M7 access token	Signed compact JWT; clients must treat it as opaque	Authorization: Bearer <token>	Protected /v1/convert, /v1/document, and /v1/job routes

The Document API does not issue credentials. Obtain an access token through an M7 SSO flow appropriate to the caller:

• Use authorization code with PKCE for a user-facing application.
• Use device authorization for a CLI, TV, or other input-constrained device.
• Use client_credentials for an eligible confidential machine client acting as itself.
• Use the SSO token endpoint to exchange, refresh, or replace credentials as permitted by the OAuth client's policy.

The SSO discovery document is available at https://sso.user.m7.org/.well-known/openid-configuration, and token exchanges use POST https://sso.user.m7.org/token. Follow the M7 SSO token documentation for grant fields and the client's configured authentication method.

Refresh tokens, ID tokens, authorization codes, device codes, client secrets, and DPoP proofs do not replace an access token on Document API routes. Send those credentials only to the SSO endpoint or flow that defines them.

Send an authenticated request

Send the access token in the Authorization header using the Bearer scheme:

curl --fail-with-body --silent --show-error \
  --request POST 'https://api.document.m7.org/v1/job/list' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

Do not put an access token in a URL, query string, request body, or cookie. Do not rely on alternate token headers even if an intermediary accepts them. Never log a complete access token or Authorization header.

M7 access tokens are JWTs, but decoded claims are not proof that a token is valid or authorized for a Document API resource. Treat the token as opaque and use API responses as the authorization decision.

The Document API accepts the current M7 token profile issued by id.m7.org with an RS512 signature and a trusted HTTPS certificate source on that host. It validates the signature and any nbf, iat, and exp time claims present in the token. The service does not currently require a particular aud claim; callers must still request tokens and scopes allowed by their SSO client policy. It also does not apply a per-route OAuth scope claim; the active principal's stored role and job ownership provide the service authorization boundary.

DPoP status

DPoP is not part of the supported Document API authorization contract. The service authenticates resource requests as Bearer requests and does not validate a DPoP proof's signature, HTTP method and URL binding, access-token binding, freshness, unique identifier, or replay state. CORS allowance and header parsing for DPoP, HTU, or related fields do not provide end-to-end DPoP enforcement.

If an SSO credential lineage requires DPoP at the SSO token endpoint, follow that SSO contract for token acquisition or refresh. Do not rely on a DPoP proof to authorize or protect a request to api.document.m7.org.

Principals and authorization boundaries

After token validation, the service uses the token's id or sub identity to resolve a local principal. A newly seen supported identity may be registered as an active principal of the default user kind. Later requests use the current stored principal status and role; possession of a signed token does not override a disabled or otherwise inactive principal.

Principal role	Supported public use
user	Calls protected conversion, document, and job routes; job access is limited to jobs owned by that principal.
admin or root	Calls the same public routes and may inspect or manage jobs across owners where the job route supports privileged access.

The protected public route families accept active user, admin, and root principals:

Route family	Authorization boundary
/v1/convert/*	Requires an active allowed principal. A created conversion job is owned by that principal.
/v1/document/*	Requires an active allowed principal. Synchronous operations are recorded under that principal.
/v1/job/*	Requires an active allowed principal. A user can list, retrieve, read results for, cancel, or delete only its own jobs.

A job UUID does not grant access by itself. For a non-privileged caller, a job owned by another principal is returned as not found rather than revealing that the job exists. Privileged behavior depends on the principal's current stored role, not merely on a caller-supplied owner value.

Expiry, refresh, and revocation

• Stop using an access token when its reported lifetime ends. The Document API does not extend access-token lifetimes.
• When the SSO flow supplies a refresh package, send the refresh_token and its required binding values only to POST https://sso.user.m7.org/token, together with the owning OAuth client's configured authentication. Never send refresh material to the Document API.
• A client_credentials access token has no user refresh session. Obtain a replacement by authenticating the confidential client to SSO again.
• Revoke an eligible token through POST https://sso.user.m7.org/revoke using the SSO client's required authentication. The Document API has no local token-revocation endpoint.
• Document API access can end independently of token expiry when the local principal becomes inactive. Conversely, the service validates JWTs locally and does not perform token introspection for every request, so a revoked access token may remain accepted until its signed validity period ends.

Follow the M7 SSO lifecycle documentation for refresh rotation, revocation, and terminal credential states. After a terminal refresh or revocation error, discard the unusable package and begin a new supported authorization flow instead of retrying indefinitely.

Authentication and authorization failures

Protected-route failures use the Document API error envelope. A missing or unusable principal returns HTTP 401; a resolved principal that does not meet the route's status or role rule returns HTTP 403.

{
  "status": 0,
  "code": 401,
  "comment": "Access denied",
  "reason": "missing_principal",
  "data": {}
}

Failure	Typical cause	Client action
HTTP 401, missing_principal	The Bearer header is missing, the token cannot be validated, or its claims cannot resolve an identity	Send a valid M7 access token; if one was already sent, discard it and obtain a replacement from SSO
HTTP 403, principal_role_denied	The current principal role is not allowed for the route	Use a principal with the required role; do not retry with caller-supplied role data
HTTP 403, inactive-principal reason	The resolved local principal is pending, disabled, or otherwise inactive	Restore the principal's access or use another authorized principal
HTTP 404, Job not found	The job does not exist or is owned by another principal	Check the job ID and use the principal that created the job

Do not branch only on the human-readable comment. Handle the HTTP status and the response's machine-oriented reason when present.

Security checklist

• Use TLS and the exact https://api.document.m7.org production host.
• Keep access tokens, refresh packages, client secrets, authorization codes, device codes, and DPoP private keys out of source control, logs, analytics, URLs, and error reports.
• Store short-lived access tokens and long-lived refresh credentials using protection appropriate to their lifetime and caller environment.
• Request only the grants and scopes required by the integration.
• Revoke and replace credentials after suspected disclosure.
• Treat job identifiers as references, not credentials; the service still applies principal ownership and role checks.

Related documentation:

• M7 SSO API
• Document API