# 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:

```text
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](https://m7.org/docs/api/sso.user.m7.org/) 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.

```bash
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:

```bash
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](https://m7.org/docs/api/api.bigfs.m7.org/workspaces.md) 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.

```bash
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:

- [M7 SSO API](https://m7.org/docs/api/sso.user.m7.org/)
- [BigFS API](https://m7.org/docs/api/api.bigfs.m7.org/)

## Organization acquisition boundary

The [organization endpoint/search routes](https://m7.org/docs/api/api.bigfs.m7.org/organizations.md) 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.
