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.
- Call
/v1/offline_access/oauth/device/issuewith the current Bearer token. - Show the returned
verification_urianduser_codeto the user. - Poll
/v1/offline_access/oauth/device/pickupwith the returned recordid, waiting at least the returnedintervalbetween calls. - On the first successful pickup, store the returned access token, refresh
token,
binding_chain, andbinding_linksecurely. 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.orgproduction 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.