Authorization

api.drop.m7.org uses an M7 access token to identify the caller and a drop-specific key to authorize access to an encrypted payload. These credentials have different purposes: an access token establishes the caller's principal, while a drop key unlocks one drop's payload.

The production API base URL is:

https://api.drop.m7.org

Choose an authorization mode

Operation	Required credentials
Create or manage a drop through `/v1/drop/*`	M7 access token. Payload reads and consumption also require the drop `id` and `key`.
Consume a private drop through `/v1/consume`	The owner's M7 access token plus the drop `id` and `key`.
Consume a drop created with `anonymous: true` through `/v1/consume`	Drop `id` and `key`; no access token is required.

An anonymous drop is not public data. Its 64-character key remains secret and is required with its id to retrieve the payload.

M7 access tokens

Format and acquisition

This API accepts M7 access tokens issued by M7 SSO. An access token is a signed JWT, but clients should treat it as opaque: decoding a token does not validate it and applications must not make authorization decisions from unverified claims.

Obtain an access token through the appropriate flow in the M7 SSO authorization guide:

authorization code with PKCE for a user-facing application;
device authorization for a CLI or input-constrained device; or
client credentials for a confidential server application acting as itself.

api.drop.m7.org does not issue access or refresh tokens. Client secrets, authorization codes, refresh tokens, ID tokens, and refresh-package binding values are sent only to M7 SSO as specified by that guide; this API does not accept them as credentials.

Transport

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

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

Do not place an access token in a URL, query string, JSON body, or cookie. Use HTTPS for every request.

Validation and principal construction

The API validates the M7 token's signature, id.m7.org issuer, and applicable time claims before constructing a service principal. The principal identifier comes from the token's id or sub claim and becomes the owner identifier for drops created by that principal. A token must resolve to an active principal with an effective user, admin, or root role to call /v1/drop/*.

The caller's principal can represent an M7 user or an OAuth application acting as itself. The resulting owner boundary is the same: credentials for one principal do not grant access to another principal's drops.

Role and ownership boundaries

Route family or operation	Authorization boundary
`/v1/drop/reserve` and `/v1/drop/store`	The authenticated principal becomes the drop owner.
`/v1/drop/activate`, `/v1/drop/get`, `/v1/drop/status`, `/v1/drop/list`, `/v1/drop/revoke`, and `/v1/drop/consume`	The authenticated principal may act only on its owned drops.
`/v1/drop/delete`	An owner may delete its drop. An `admin` or `root` principal may delete another principal's drop.
`/v1/consume` for a private drop	The access-token principal must match the drop owner.
`/v1/consume` for an anonymous drop	The `id` and `key` authorize consumption; an access token is not required.

An admin or root role does not bypass ownership on the other public drop operations.

Bearer request example

curl --fail-with-body --silent --show-error \
  --request POST 'https://api.drop.m7.org/v1/drop/status' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "DROP_ID"
  }'

Drop IDs and keys

A drop id and key are lowercase or uppercase 64-character hexadecimal strings. The id identifies a drop and is not confidential by itself. The key is secret material used to verify access and decrypt that drop's payload.

Acquisition and storage

The caller may supply a 64-character key when storing or activating a drop. If the key is omitted, the API generates it and returns it only in the successful /v1/drop/store or /v1/drop/activate response. The API cannot recover a generated key later.

Store the key in secret storage and disclose it only to the intended recipient. Do not place it in a URL or query string, browser history, logs, analytics, or support material.

Transport and scope

Send the id and key as JSON fields over HTTPS:

{
  "id": "DROP_ID",
  "key": "DROP_KEY"
}

The key is scoped to one drop. It is required for a keyed read through /v1/drop/get and for consumption through /v1/drop/consume or /v1/consume. A key does not bypass the owner check on /v1/drop/*, and it does not bypass the owner check on /v1/consume unless the drop was created with anonymous: true.

Anonymous consumption example

curl --fail-with-body --silent --show-error \
  --request POST 'https://api.drop.m7.org/v1/consume' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "DROP_ID",
    "key": "DROP_KEY"
  }'

Private consumption example

curl --fail-with-body --silent --show-error \
  --request POST 'https://api.drop.m7.org/v1/consume' \
  --header 'Authorization: Bearer ACCESS_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "id": "DROP_ID",
    "key": "DROP_KEY"
  }'

Drop-key lifetime

A key can unlock a payload only while its drop is active and unexpired. A keyed /v1/drop/get reads the payload without consuming it. A successful consume changes the drop to consumed and clears its stored payload, so it cannot be repeated. Revoking the drop also clears the payload; expiration or deletion makes the key unusable.

Token expiry, refresh, and revocation

Access-token expiration is enforced by the API. After an access token expires, obtain a replacement through M7 SSO; if the authorization flow issued a refresh package, refresh it only at the SSO token endpoint and keep the whole package together as described in the M7 SSO authorization guide.

Revoke an M7 token through the SSO revocation endpoint. Stop using and discard a token immediately after revocation or suspected disclosure. This API checks signed-token validity locally, so clients must not use it as a token introspection or revocation-status endpoint.

The drop lifecycle is separate from the M7 token lifecycle. Use /v1/drop/revoke to revoke an owned drop; this clears its payload but does not revoke the caller's M7 token.

DPoP status

DPoP is not part of the supported api.drop.m7.org authorization contract. The service does not validate a proof's signature, method and URL binding, access-token binding, freshness, identifier, or replay state. Send the access token with Authorization: Bearer; do not infer DPoP support from CORS header allowance or platform parsing capability.

Authentication and authorization errors

Authorization failures use the API's JSON error envelope. A principal-gate failure includes a machine-readable reason:

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

HTTP status	Meaning and next action
`401`	The protected route has no usable access-token principal. Supply a valid token or obtain a replacement if it expired.
`403`	The authenticated principal has the wrong role, does not own the requested private drop, or otherwise crosses an authorization boundary. Do not retry with the same identity.
`404`	No accessible drop matches the supplied `id`, ownership boundary, and—when required—`key`. Do not use this response to probe for another principal's drops.
`409`	The drop's lifecycle state does not permit the requested action. Refresh the drop status before deciding whether another action is valid.
`410`	The drop has expired. Its payload is no longer readable or consumable.

Treat the text in comment as diagnostic. Branch primarily on the HTTP status and, when present, the stable reason value.

Security checklist

Keep access tokens and drop keys out of URLs, logs, analytics, and support material.
Store access tokens only as long as needed; keep refresh credentials in durable secret storage and send them only to M7 SSO.
Keep confidential-client secrets on a trusted backend, never in browser, native, CLI, or device code that an end user can extract.
Share an anonymous drop's id and key only with its intended recipient.
Revoke the drop and the M7 token independently when either credential may have been exposed.
Use fresh placeholders—not production credentials—in tests and examples.