Authorization for api.bigfs.m7.org

BigFS accepts M7 access tokens and then applies its own principal, bucket, and vault access rules. A valid token identifies the caller; it does not grant unrestricted access to stored objects.

The API base URL is:

https://api.bigfs.m7.org

Supported credentials

Credential	Public transport	Where it applies	What BigFS validates
M7 consumer access token	Authorization: Bearer <token>	Authenticated routes unless an endpoint documents a narrower rule	Token signature, issuer and validity times; consumer token mode; an active BigFS principal; and the endpoint's resource-access rules
M7 access token for uploads	Authorization: Bearer <token>	/v1/upload/form_data and /v1/upload/post_data	Token validity, an active BigFS principal, and owner or admin access to the target bucket; upload routes do not impose the consumer-versus-tenant token-mode check
Offline-access refresh package	An opaque refresh_token plus its secret binding_chain and binding_link; send only to the issuing M7 SSO token endpoint using the owning OAuth client's authentication	Refreshing a token bundle obtained through the BigFS device helper	The SSO provider's client, binding, rotation, expiry, and revocation rules; BigFS resource routes do not accept refresh packages
One-time download grant	The id and secret key in the issued /v1/download/link URL	One download through /v1/download/link	A matching, unexpired, unused grant

BigFS uses a confidential OAuth client internally for its offline-access device helper. That client secret is server-held and is never a caller credential. ID tokens, refresh tokens, OAuth client secrets, device codes, and user codes do not replace a Bearer access token on BigFS resource routes.

Some delivery routes are intentionally unauthenticated. In particular, /v1/public/redir/<bucket>/<name> accepts no credential. Its availability does not make an authenticated bucket or object public through another route.

Obtain an access token

Obtain the initial consumer access token through an M7 SSO flow appropriate to the caller. See the M7 SSO API documentation for the authorization, token, device, refresh, and revocation contracts.

BigFS also provides an authenticated device helper for obtaining an offline-access bundle for the current principal. This helper is not an unauthenticated sign-in bootstrap: both helper routes require an existing consumer access token.

1. Call /v1/offline_access/oauth/device/issue with the current Bearer token.
2. Show the returned verification_uri and user_code to the user.
3. Poll /v1/offline_access/oauth/device/pickup with the returned record id, waiting at least the returned interval between calls.
4. On the first successful pickup, store the returned access token, refresh token, binding_chain, and binding_link securely. A later pickup of the redeemed record confirms success but does not return the package again.

curl --request POST \
  'https://api.bigfs.m7.org/v1/offline_access/oauth/device/issue' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"label":"Desktop backup"}'

The helper's default requested scope is openid profile email groups offline_access. The response reports expires_in for the access token and refresh_expires_in for the refresh token. Treat the refresh token and both binding values as opaque secrets; they form one refresh package. The service supplies its own OAuth client authentication to SSO during issue and pickup, and callers must not send a client secret to BigFS.

Send a Bearer request

Send the access token in the Authorization header:

curl --request POST \
  'https://api.bigfs.m7.org/v1/bucket/search' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{}'

M7 access tokens are signed compact JWTs, but clients should treat them as opaque. Decoded claims are not proof that a token is current, accepted by BigFS, or authorized for a resource.

The public integration contract is Authorization: Bearer <token>. Do not put access tokens in URLs, query strings, request bodies, or cookies, and do not depend on compatibility token transports. Never log a complete token or authorization header.

BigFS currently accepts M7 tokens issued by id.m7.org with the supported RS512 signature profile. It verifies the signature and trusted certificate source and enforces the token's time claims. Most authenticated routes also require consumer token mode; a tenant token is rejected there even when its signature is valid.

DPoP status

DPoP is not part of the supported BigFS authorization contract. BigFS reduces resource authentication to Bearer-token validation and does not validate a DPoP proof's signature, method and URL binding, access-token binding, freshness, unique identifier, or replay state. Header parsing or CORS allowance for a DPoP header does not change that contract. Send the Bearer request described above and do not rely on a DPoP proof to authorize a BigFS request.

Principal and resource authorization

After token validation, BigFS resolves the token's id or sub identity to a local principal. The principal must be active. A newly seen supported identity can be registered as an active BigFS user principal; later requests use the current local principal record rather than trusting a decoded role claim as the complete authorization decision.

Resource access is evaluated from current BigFS relationships:

Boundary	Authorization behavior
Bucket membership	Any active bucket member can read the bucket and related objects, keys, remote-object records, task records, and authorized downloads.
Bucket owner or admin	Required to change bucket contents, delete objects or keys, upload data, delete the bucket, process tasks, and manage bucket members. Admins cannot manage owner or admin memberships, and the final owner cannot be removed or demoted.
Vault membership	Any active vault member can read the vault.
Vault owner or admin	Required to change or delete a vault, manage linked buckets, and inspect the vault's available handlers.
Vault owner	Required to add, change, or remove vault-management principals. The final owner cannot be removed or demoted.
BigFS root principal	Required when a new vault selects a private handler.
Offline-access record ownership	A caller can pick up only the device record created for that same BigFS principal.

Creating a bucket or vault makes the current principal its owner. Possession of another principal's resource UUID does not bypass membership checks. A token that is valid for one principal, bucket, or vault does not authorize access to another principal's resources.

The upload routes are the token-mode exception: they accept a cryptographically valid M7 access token without requiring consumer mode, but they still require an active local principal and owner or admin membership on the target bucket.

One-time download grants

An authorized bucket member can call /v1/download/issue with a consumer Bearer token. BigFS returns a grant containing an opaque id and secret key, plus a ready-to-use URL. The grant expires after 120 seconds and is consumed by the first successful /v1/download/link request.

curl --request POST \
  'https://api.bigfs.m7.org/v1/download/issue' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{"id":"ASSET_UUID"}'

Use the exact returned URL to retrieve the file; no Bearer header is required on the link request. The URL itself is a credential. Share it only with the intended recipient, avoid storing it in logs or analytics, and consume it promptly. A missing, mismatched, expired, or already-consumed grant fails and cannot be refreshed; issue a new grant through the authenticated route.

Expiry, refresh, and revocation

• Stop using an access token when its reported lifetime ends. Obtain a replacement through its SSO flow; BigFS does not extend access-token lifetimes.
• Send refresh packages only to the issuing M7 SSO token endpoint. A refresh exchange requires the refresh_token, binding_chain, binding_link, and the owning OAuth client's authentication. Never send this material to a BigFS resource route or place it in a URL.
• The BigFS device helper does not expose a public refresh or revocation operation. Do not assume that possession of its returned refresh package grants permission to act as BigFS's confidential OAuth client. An authorized owner of that client must follow the M7 SSO rotation and revocation contract; other integrations should obtain a replacement through their supported authorization flow.
• Resource access can also end while a token remains cryptographically valid: disabling the BigFS principal or removing its bucket or vault membership causes later authorization checks to fail.
• A device request can end in access_denied, expired_token, or another terminal OAuth error. Start a new device request instead of continuing to poll a terminal record.
• A download grant expires after 120 seconds or when consumed. It has no refresh operation.

Common failures

BigFS JSON failures use status: 0 with a diagnostic comment. Upload authorization failures use HTTP 401 for a missing principal and HTTP 403 for other access denials, with details under data.authorization. Treat comments and diagnostic fields as troubleshooting information rather than a stable machine-error protocol.

Failure	Typical cause	Client action
Missing token	No Bearer access token was supplied	Add the Authorization header; do not substitute an ID or refresh token
Token validation failure	Malformed token, unsupported signature, bad issuer or certificate, or invalid validity time	Discard the token and obtain a new one from SSO
This endpoint requires a consumer token	A tenant-mode token was sent to a consumer route	Obtain a consumer token or use only a route that explicitly accepts the other mode
Principal unavailable or inactive	The token identity cannot resolve to an active BigFS principal	Reauthenticate; if the failure persists, restore the principal rather than retrying blindly
Bucket access denied	The principal lacks membership or the required bucket role	Use an authorized principal or have a bucket owner grant the required role
Vault access denied	The principal lacks membership or the required vault role	Use an authorized principal or have a vault owner grant the required role
Device pickup remains pending	The user has not completed verification	Wait at least the reported polling interval and try again
Device pickup returns slow_down	The client polled too quickly	Replace the old interval with the larger interval returned by BigFS
Download grant failure	The grant is missing, mismatched, expired, or consumed	Request a new grant with an authorized consumer token

Security checklist

• Use TLS and the exact https://api.bigfs.m7.org production host.
• Keep access tokens, refresh packages, download-grant URLs, and OAuth client secrets out of source control, logs, analytics, and error reports.
• Treat signed JWT contents as untrusted client-side hints; rely on BigFS responses for authorization decisions.
• Request only the scopes required by the issuing flow and store offline-access refresh tokens using protection appropriate for long-lived credentials.
• Revoke and replace credentials after suspected disclosure.
• Check each endpoint's documented bucket, vault, principal, and role boundary before enabling an integration.

Related documentation:

• M7 SSO API
• BigFS API