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 accepts M7 tokens issued by the current https://sso.user.m7.org authority and the exact legacy id.m7.org issuer value. It trusts signing certificates only from sso.user.m7.org and id.m7.org, requires the supported RS512 signature profile, and requires the token audience https://api.bigfs.m7.org. 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 uses M7Roster's canonical principal ID for resource membership and ownership. Native token sub and the roster's rid remain identity references; they are not the resource membership key. Consumer and admitted tenant callers need a valid signed m7.principal projection with active receiving-service admission. Missing, pending or denied projections do not automatically become active local users.

Application callers additionally require a fresh, receiver-authenticated SSO ACL decision on every request. Configure the receiving registration's M7_CLIENT_ID, M7_CLIENT_SECRET and supported authentication method on the server. The sending application's list role and stored roster role are not fallback grants. Verified personal owner proxies use M7Roster's current owner binding; the organization acquisition routes retain their narrower eligibility. Sender-bound machine tokens remain denied until inbound proof enforcement is supported by the roster.

The local roster table stores stable reference information and supports member target/display lookup. Current caller decisions use the validated token or receiver ACL, independently of stored rows. Existing bucket/vault relationships still determine resource access; switching the controller to M7Roster requires an explicit migration of legacy member principal references.

Bucket and vault authority comes from their single pinned Management association in Groups V2. Effective access requires active group, membership and link state. A role in another linked group does not confer Management access. Membership management checks and final-owner protection run inside the V2 lock and transaction lifetime.

Membership removal marks the row removed and revokes access. Adding that principal again explicitly reactivates the same membership ID. Resource deletion retires its pinned links and related storage assignments while keeping membership history. Vault-to-bucket and handler-to-vault assignments retain their own typed resource references.

Resource access is evaluated from current BigFS relationships:

Boundary Authorization behavior
Bucket membership Active members can list accessible bucket summaries and use membership-scoped object, key, task and download reads. Bucket refresh through view additionally requires bucket.get, currently within the owner/admin profile.
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.
Current validated BigFS root caller 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 makes the selected user or authorized organization principal its owner. Personal applications cannot create buckets. Creating a 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.

Organization workspace and exact action grants

Select a supported organization operation with Org: ORG_UUID or JSON org_id; supply Org-DPoP or orgs_dpop only for an SSO-bound organizations proof. A fresh recipient-authenticated SSO lookup supplies direct Management facts on every selected-organization operation, including reads. Resource capabilities are intersected with those live grants and current pinned bucket Management membership. An organization role, tag or resource UUID alone grants no resource access. Verified empty tag selections allow owner/admin defaults; Members have no automatic grant. Explicit selections replace defaults, and unknown selections grant nothing.

Use /v1/bucket/context for the selected principal and actor IDs, current resource role and exact capabilities. Bucket view refresh/save uses bucket.get/bucket.save, delete preview/delete uses bucket.delete_status/bucket.delete, and membership changes use their exact bucket.access.* actions. These capability checks retain role and final-owner restrictions. Ordinary member/viewer read access does not imply bucket.get or management-list permission.

The workspace guide lists the supported selected-organization routes and request/proof fields. A selected organization on another resource operation fails with 403; retain the same workspace selection on subsequent resource requests.

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. Roster admission uses HTTP 401 for missing/invalid caller tokens or unsupported sender proof, 503 for missing receiver authentication or ACL lookup failure, and 403 for principal/role denial. Upload admission includes details under data.authorization; other roster denials expose data.reason and data.boundary. 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
Receiving principal unavailable or inactive The signed principal projection or current receiver ACL denies admission Obtain a fresh token and verify receiving-list status and role
Receiver ACL unavailable Receiving client authentication is absent or SSO lookup failed Configure the receiving registration or restore its ACL lookup before retrying
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:

Organization acquisition boundary

The organization endpoint/search routes require a canonical SSO user or ordinary application token and registered, explicitly requested orgs (with consent for consumer sign-in), plus a separate SSO endpoint proof when bound. These two routes allow app tokens from either directory mode; tenant member tokens and personal owner proxies remain ineligible. They forward live role/tag/pub facts and consumer/tenant app identities through the platform/SDK; those facts alone do not authorize bucket or vault operations. Workspace selection separately verifies the receiving organization and intersects its Management grants with pinned bucket membership. Local imports persist org identity only; caller permission facts and app lists remain live.