Skip to content

README.md

Latest commit

 

History

History
203 lines (132 loc) · 48.5 KB

README.md

File metadata and controls

203 lines (132 loc) · 48.5 KB
Raw

M2m

Overview

Available Operations

create_token

Creates a new M2M Token. Must be authenticated via a Machine Secret Key.

Example Usage

import clerk_backend_api
from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.m2m.create_token(token_format=clerk_backend_api.TokenFormat.OPAQUE, seconds_until_expiration=9240.85, claims="<value>", min_remaining_ttl_seconds=240)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description Example
token_format Optional[models.TokenFormat] ➖ N/A
seconds_until_expiration OptionalNullable[float] ➖ N/A
claims OptionalNullable[Any] ➖ N/A
min_remaining_ttl_seconds Optional[int] ➖ Enables server-side token reuse for opaque-format tokens. When set, if a non-revoked, non-expired M2M token already exists for this machine with identical claims and scopes and at least this many seconds of remaining lifetime, that existing token is returned and no new token is minted.

Use this when caching tokens in application memory across requests is impractical — for example, in serverless functions, short-lived job workers, or autoscaling containers that churn faster than the token TTL. Pooling at the server collapses many redundant create calls into reuse of a single live token, which is the recommended pattern for high-volume M2M traffic.

Must be strictly less than the effective token lifetime — that is, seconds_until_expiration when provided, or the machine's default TTL otherwise. A value greater than or equal to the lifetime is rejected with a 400, since no freshly-minted token would ever satisfy the requirement.

Only applies to opaque-format tokens (token_format defaults to opaque). JWT-format tokens are stateless and are never deduplicated.		 240
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.CreateM2MTokenResponseBody

Errors

Error Type Status Code Content Type
models.CreateM2MTokenM2mResponseBody 400 application/json
models.CreateM2MTokenM2mResponseResponseBody 409 application/json
models.SDKError 4XX, 5XX */*

list_tokens

Fetches M2M tokens for a specific machine.

Only tokens created with the opaque token format are returned by this endpoint. JWT-format M2M tokens are stateless and are not stored.

This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.

  • When fetching M2M tokens with a Machine Secret Key, only tokens associated with the authenticated machine can be retrieved.
  • When fetching M2M tokens with a Clerk Secret Key, tokens for any machine in the instance can be retrieved.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.m2m.list_tokens(subject="<value>", revoked=False, expired=False, limit=10, offset=0)

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
subject str ✔️ N/A
revoked OptionalNullable[bool] ➖ N/A
expired OptionalNullable[bool] ➖ N/A
limit Optional[float] ➖ N/A
offset OptionalNullable[float] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.GetM2MTokensResponseBody

Errors

Error Type Status Code Content Type
models.GetM2MTokensM2mResponseBody 400 application/json
models.GetM2MTokensM2mResponseResponseBody 403 application/json
models.GetM2MTokensM2mResponse404ResponseBody 404 application/json
models.SDKError 4XX, 5XX */*

revoke_token

Revokes a M2M Token.

This endpoint only revokes stored opaque-format M2M tokens. JWT-format M2M tokens are stateless and cannot be revoked.

This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.

  • When revoking a M2M Token with a Machine Secret Key, the token must managed by the Machine associated with the Machine Secret Key.
  • When revoking a M2M Token with a Clerk Secret Key, any token on the Instance can be revoked.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.m2m.revoke_token(m2m_token_id="<id>", revocation_reason="<value>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
m2m_token_id str ✔️ N/A
revocation_reason OptionalNullable[str] ➖ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.RevokeM2MTokenResponseBody

Errors

Error Type Status Code Content Type
models.RevokeM2MTokenM2mResponseBody 400 application/json
models.RevokeM2MTokenM2mResponseResponseBody 404 application/json
models.SDKError 4XX, 5XX */*

verify_token

Verifies a M2M Token.

This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key.

  • When verifying a M2M Token with a Machine Secret Key, the token must be granted access to the Machine associated with the Machine Secret Key.
  • When verifying a M2M Token with a Clerk Secret Key, any token on the Instance can be verified.

Example Usage

from clerk_backend_api import Clerk


with Clerk(
    bearer_auth="<YOUR_BEARER_TOKEN_HERE>",
) as clerk:

    res = clerk.m2m.verify_token(token="<value>")

    # Handle response
    print(res)

Parameters

Parameter Type Required Description
token str ✔️ N/A
retries Optional[utils.RetryConfig] ➖ Configuration to override the default retry behavior of the client.

Response

models.VerifyM2MTokenResponseBody

Errors

Error Type Status Code Content Type
models.VerifyM2MTokenM2mResponseBody 400 application/json
models.VerifyM2MTokenM2mResponseResponseBody 404 application/json
models.SDKError 4XX, 5XX */*