Stytch – The most powerful identity platform built for developers

Start M2M Client Secret Rotation

POST

https://test.stytch.com/v1/m2m/clients/{client_id}/secrets/rotate/start

Initiate the rotation of an M2M client secret. After this endpoint is called, both the client's client_secret and next_client_secret will be valid. To complete the secret rotation flow, update all usages of client_secret to next_client_secret and call theRotate Secret Endpoint to complete the flow.Secret rotation can be cancelled using theRotate Cancel Endpoint.

Important: This is the only time you will be able to view the generated next_client_secret in the API response. Stytch stores a hash of the next_client_secret and cannot recover the value if lost. Be sure to persist the next_client_secret in a secure location. If the next_client_secret is lost, you will need to trigger a secret rotation flow to receive another one.

Path parameters

client_id* string

The ID of the client.

Response fields

status_code int

The HTTP status code of the response. Stytch follows standard HTTP response status code patterns, e.g. 2XX values equate to success, 3XX values are redirects, 4XX are client errors, and 5XX are server errors.

request_id string

Globally unique UUID that is returned with every API call. This value is important to log for debugging purposes; we may ask for this value to help identify a specific API call when helping you debug an issue.

m2m_client object

The M2M Client affected by this operation.

client_id string

The ID of the client.

next_client_secret string

The newly created secret that's next in rotation for the client. Important: this is the only time you will be able to view the next_client_secret. Be sure to persist the next_client_secret in a secure location. If the next_client_secret is lost, you will need to trigger a secret rotation flow to receive another one.

client_name string

A human-readable name for the client.

client_description string

A human-readable description for the client.

client_secret_last_four string

The last four characters of the client secret.

next_client_secret_last_four string

The last four characters of the next_client_secret. Null if no next_client_secret exists.

status string

The status of the client - either active or inactive.

scopes array[strings]

An array of scopes assigned to the client.

trusted_metadata object

An arbitrary JSON object for storing application-specific data.

const stytch = require('stytch');

const client = new stytch.Client({
  project_id: 'PROJECT_ID',
  secret: 'SECRET',
});

const params = {
  client_id: "m2m-client-test-d731954d-dab3-4a2b-bdee-07f3ad1be885",
};

client.m2m.clients.secrets.rotateStart(params)
  .then(resp => { console.log(resp) })
  .catch(err => { console.log(err) });

RESPONSE 200

{
    "status_code": 200,
    "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
    "m2m_client": {
        "client_id":"m2m-client-test-d731954d-dab3-4a2b-bdee-07f3ad1be885",
        "next_client_secret":"NHQhc7ZqsXJVtgmN2MXr1etqsQrGAwJ-iBWNLKY7DzJj",
        "client_name":"Example client name",
        "client_description":"Example client description.",
        "client_secret_last_four":"DzJj",
        "next_client_secret_last_four":"DzJj",
        "status":"active",
        "scopes":["read:users","write:users"],
        "trusted_metadata":{}
    }
}

RESPONSE 404

{
  "status_code": 404,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "m2m_client_not_found",
  "error_message": "The m2m client requested could not be found.",
  "error_url": "https://stytch.com/docs/api/errors/404"
}

RESPONSE 429

{
  "status_code": 429,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "too_many_requests",
  "error_message": "Too many requests have been made.",
  "error_url": "https://stytch.com/docs/api/errors/429"
}

RESPONSE 500

{
  "status_code": 500,
  "request_id": "request-id-test-b05c992f-ebdc-489d-a754-c7e70ba13141",
  "error_type": "internal_server_error",
  "error_message": "Oops, something seems to have gone wrong, please reach out to support@stytch.com to let us know what went wrong.",
  "error_url": "https://stytch.com/docs/api/errors/500"
}

Delete

Via email

Embeddable

Start

Reset options

Via SMS

Via Whatsapp

Via email

Register

Authenticate

Token

M2M Client

Rotate secret

Tokens

Configuration

Methods

Consent Management

Application Management

Rotate secret

Start M2M Client Secret Rotation

Path parameters

Response fields

Common Error Types