M2M overview - Stytch Docs

M2M authentication flow

  1. Create an M2M client
    Create an M2M client to get credentials for authentication using the Create M2M Client endpoint:

    curl --request POST \
  --url https://test.stytch.com/v1/m2m/clients \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
    "client_name": "Production API Service",
    "client_description": "Backend service for processing orders",
    "scopes": ["read:orders", "write:orders"]
  }'

    Response: 

    {
  "status_code": 201,
  "m2m_client": {
    "client_id": "m2m-client-test-d731954d-dab3-4a2b-bdee-07f3ad1be885",
    "client_secret": "secret-test-...",
    "client_name": "Production API Service",
    "client_description": "Backend service for processing orders",
    "status": "active",
    "scopes": ["read:orders", "write:orders"]
  }
}

    Store the client_id and client_secret securely - the secret is only returned once at creation.

  2. Get an access token
    Use the client credentials to obtain an access token using the Get Access Token endpoint:

    curl --request POST \
  --url https://test.stytch.com/v1/m2m/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --user 'm2m-client-test-d731954d-dab3-4a2b-bdee-07f3ad1be885:secret-test-...' \
  --data 'grant_type=client_credentials'

    Response: 

    {
  "status_code": 200,
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600
}

    Access tokens are JWTs signed with your project’s JWKS and are valid for one hour.

  3. Use the access token
    Include the access token in API requests:

    curl --request GET \
  --url https://api.yourapp.com/orders \
  --header 'Authorization: Bearer eyJhbGc...'

    Validate tokens using the Authenticate Access Token method in the Stytch Backend SDKs or any JWT validation library.

Managing M2M clients

Update client settings like name, description, or scopes using the Update M2M Client endpoint:

curl --request PUT \
  --url https://test.stytch.com/v1/m2m/clients/m2m-client-test-d731954d-dab3-4a2b-bdee-07f3ad1be885 \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
  "client_name": "Updated Service Name",
  "scopes": ["read:orders", "write:orders", "read:customers"]
}'

Updating scopes affects future access tokens but doesn’t invalidate existing ones.

Search for M2M clients by name or other criteria using the Search M2M Clients endpoint:

curl --request POST \
  --url https://test.stytch.com/v1/m2m/clients/search \
  --header 'Content-Type: application/json' \
  --user 'PROJECT_ID:SECRET' \
  --data '{
  "query": {
      "operator": "AND",
      "operands": [\
        {\
          "filter_name": "status",\
          "filter_value": ["active"]\
        }\
      ]
    }
  }'

Returns all M2M clients matching the search criteria.

Delete an M2M client using the Delete M2M Client endpoint:

curl --request DELETE \
  --url https://test.stytch.com/v1/m2m/clients/m2m-client-test-d731954d-dab3-4a2b-bdee-07f3ad1be885 \
  --user 'PROJECT_ID:SECRET'

Deleting a client immediately invalidates its credentials. Existing access tokens remain valid until expiration.

Access token claims

M2M access tokens are JWTs containing standard claims:

{
  "sub": "m2m-client-test-d731954d-dab3-4a2b-bdee-07f3ad1be885",
  "iss": "stytch.com/project-test-...",
  "aud": ["project-test-..."],
  "exp": 1234567890,
  "iat": 1234564290,
  "scope": "read:orders write:orders"
}

Key claims:

You can add custom claims using claim templates configured in your project settings.

Learn more

[**M2M Client object**
M2M Client object reference](/content/docs/api-reference/b2b/api/m2m/m2m-client-object/index.html)
[**Get JWKS**
Retrieve public keys for token validation](/content/docs/api-reference/b2b/api/sessions/get-jwks/index.html)