Client credentials tokens

Use this API family to issue a client_credentials access token from a signed-in browser and to manage the resulting issued-token records. For the standards-facing token endpoint, see the M7 SSO token documentation.

The issuance helper requires a consumer-user access token plus the confidential application's credentials. Search, view, and revoke require the signed-in user to own the personal application or hold active Management-group access to its organization. See the authorization guide for bound session headers and principal rules.

Endpoint summary

Route	Required fields	Authorization
/oauth/client_credentials/issue/web	client_id, aud, and client_secret when the client authentication method requires it	Any signed-in user plus valid confidential-client credentials. The signed-in user does not have to own the application.
/oauth/client_credentials/search/app	None	Signed-in owner of a personal application or Management-group user for an organization application.
/oauth/client_credentials/view	id	Same application ownership or Management-group rule.
/oauth/client_credentials/revoke	id	Same application ownership or Management-group rule.

The id used by view and revoke is the issued-record UUID, not the OAuth application record ID and not the public client_id.

Issue a token

/oauth/client_credentials/issue/web is a signed-in browser helper. The OAuth application's credentials authorize the token exchange; the signed-in user authorizes use of this helper only.

Request fields

Field	Required	Notes
client_id	Yes	Public OAuth client ID.
client_secret	Conditional	Required for client_secret_post and client_secret_basic.
aud	Yes	A single audience string, not an array.
scope	No	Space-delimited scope string.
access_expires	No	Requested lifetime in seconds. expires, expires_in, and options.expires* are accepted aliases.
claims	No	JSON object; payload is an alias.
fingerprint	No	Exactly 64 hexadecimal characters. auth.fingerprint is an alias.
label	No	Display label stored with the issued record.

A client whose token_endpoint_auth_method is none cannot use this route; the response comment is client_credentials requires a confidential client. This flow never returns a refresh token.

Request example

curl -sS https://api.user.m7.org/api/v2/oauth/client_credentials/issue/web \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "PUBLIC_CLIENT_ID",
    "client_secret": "CLIENT_SECRET",
    "aud": "https://api.example.m7.org",
    "scope": "file.read file.write",
    "access_expires": 3600,
    "claims": {
      "installation": "cli"
    },
    "fingerprint": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "label": "example CLI token"
  }'

Success response

{
  "status": 1,
  "comment": "ISSUE_WEB",
  "data": {
    "oauth": {
      "access_token": "ACCESS_TOKEN",
      "token_type": "bearer",
      "expires_in": 3600,
      "scope": "file.read file.write"
    },
    "request": {
      "client_id": "PUBLIC_CLIENT_ID",
      "aud": "https://api.example.m7.org",
      "scope": "file.read file.write",
      "access_expires": 3600,
      "fingerprint": true,
      "label": "example CLI token"
    }
  }
}

data.oauth is the issued OAuth token response. data.request is a safe request summary for the calling application; it does not echo the secret.

Search issued records

/oauth/client_credentials/search/app returns client-credentials records for applications owned by the signed-in user. It accepts the shared pagination fields (limit, page_number, offset, and cursor).

There is no server-side client_id filter on this route. Filter the returned records in your application when you need one public client. Closed records are omitted.

curl -sS https://api.user.m7.org/api/v2/oauth/client_credentials/search/app \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "limit": 20,
    "page_number": 1
  }'

A pageable response places issued records in data.items (and may also expose record details for the current page), with the shared pagination metadata.

View or revoke an issued record

Use the issued-record id returned by the search result.

curl -sS https://api.user.m7.org/api/v2/oauth/client_credentials/view \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "id": "ISSUED_RECORD_UUID" }'

curl -sS https://api.user.m7.org/api/v2/oauth/client_credentials/revoke \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "id": "ISSUED_RECORD_UUID" }'

A successful revoke returns comment: "REVOKE". It closes the issued record for this API; callers should discard the corresponding access token.

Common errors

Condition	Response comment
Missing public client ID	client_id is required
Missing client secret when required	client_secret is required
Missing audience	aud is required
Public client used for client credentials	client_credentials requires a confidential client
Unknown OAuth application	oauth client not found
Invalid fingerprint	invalid fingerprint format