> ## Documentation Index
> Fetch the complete documentation index at: https://stytch.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rotate client secrets

> Managing M2M client secret rotation.

Stytch's M2M Authentication supports secret rotation to ensure security best practices with zero downtime. Regular rotation can prevent the prolonged misuse of any compromised credentials by updating the secrets for an M2M Client.

In this guide, you'll learn how to rotate secrets for an M2M Client. By the end, you'll have:

* Started a secret rotation.
* Completed a secret rotation.
* Canceled a secret rotation.

## Before you start

In order to complete this guide, you'll need the following:

* A Stytch project. If you don't have one already, in the [Dashboard](https://stytch.com/dashboard), click on your existing project name in the top left corner of the Dashboard, click **Create Project**, and then select **B2B Authentication**.
* The `project_id` and `secret` for the **Test environment** you would like to use. These values can be accessed from the **Project ID & API keys** section of the Stytch Dashboard. You'll need to pass these values into the `Authorization` request header for most Stytch API calls.
* An active M2M Client. If you haven't created one yet, you can follow the [Authenticate an M2M Client guide](/multi-tenant-auth/authentication/m2m/authenticate-client).

## Rotating client secrets

<Steps>
  <Step title="Get the M2M Client">
    If you completed the [Authenticate an M2M Client guide](/multi-tenant-auth/authentication/m2m/authenticate-client), you should have an active M2M Client. To confirm, call the [Get M2M Client endpoint](/api-reference/b2b/api/m2m/m2m-client/get-m2m-client) with its `client_id`.

    ```sh theme={null}
    curl --request GET \
    	--url https://test.stytch.com/v1/m2m/clients/{CLIENT_ID} \
    	-u '${projectId}:${secret}'
    ```

    The response should look similar to this:

    ```javascript theme={null}
    {
    	"m2m_client": {
    		"client_description": "Following the Stytch guide.",
    		"client_id": "m2m-client-test-a50053...",
    		"client_name": "Example client",
    		"client_secret_last_four": "QqNU",
    		"next_client_secret_last_four": null,
    		"scopes": [
    			"read:settings",
    			"update:settings"
    		],
    		"status": "active",
    		"trusted_metadata": {
    			"billing_tier": "standard",
    			"api_version": "v2"
    		}
    	},
    	"request_id": "request-id-test-c50eb06f-69b4-41be-8640-0d9fd2f561ae",
    	"status_code": 200
    }
    ```

    The important field to evaluate is `next_client_secret_last_four`. If the value is `null`, proceed to the next step. If the field is already populated, the client is already in a secret rotation flow. Create a new M2M Client instead.
  </Step>

  <Step title="Start the secret rotation">
    Take the `client_id` of your active M2M Client and call the [Start Secret Rotation endpoint](/api-reference/b2b/api/m2m/rotate-secret/start-secret-rotation).

    ```sh theme={null}
    curl --request POST \
    	--url https://test.stytch.com/v1/m2m/clients/{CLIENT_ID}/secrets/rotate/start \
    	-u '${PROJECT_ID}:${SECRET}'
    ```

    ```json theme={null}
    {
    	"m2m_client": {
    		"client_description": "Following the Stytch guide.",
    		"client_id": "m2m-client-test-a50053...",
    		"client_name": "Example client",
    		"client_secret_last_four": "QqNU",
    		"next_client_secret":"NHQhc7ZqsXJ...DzJj",
    		"next_client_secret_last_four": "DzJj",
    		"scopes": [
    			"read:settings",
    			"update:settings"
    		],
    		"status": "active",
    		"trusted_metadata": {
    			"billing_tier": "standard",
    			"api_version": "v2"
    		}
    	},
    	"request_id": "request-id-test-c50eb06f-69b4-41be-8640-0d9fd2f561ae",
    	"status_code": 200
    }
    ```

    After a successful API call, the response will return the M2M Client with two newly populated fields: `next_client_secret` and `next_client_secret_last_four`.

    <Info>
      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 cancel the secret rotation (Step 4) and start the rotation all over.
    </Info>

    At this point, the active M2M Client has **two** valid secrets associated with it. Both the `client_secret` and `next_client_secret` can be used to issue access tokens.

    This is an opportune time to update your secret store to use the `next_client_secret` and replace the `client_secret` for your existing services.
  </Step>

  <Step title="Complete the secret rotation">
    Once updated with `next_client_secret`, your services can now retire the `client_secret` by completing the secret rotation.

    Call the [Rotate Secret endpoint](/api-reference/b2b/api/m2m/rotate-secret/rotate-secret) with the `client_id`.

    ```sh theme={null}
    curl --request POST \
    	--url https://test.stytch.com/v1/m2m/clients/{CLIENT_ID}/secrets/rotate \
    	-u '{PROJECT_ID}:{SECRET}'
    ```

    ```json theme={null}
    {
    	"m2m_client": {
    		"client_description": "Following the Stytch guide.",
    		"client_id": "m2m-client-test-a50053...",
    		"client_name": "Example client",
    		"client_secret_last_four": "DzJj",
    		"next_client_secret_last_four": null,
    		"scopes": [
    			"read:settings",
    			"update:settings"
    		],
    		"status": "active",
    		"trusted_metadata": {
    			"billing_tier": "standard",
    			"api_version": "v2"
    		}
    	},
    	"request_id": "request-id-test-c50eb06f-69b4-41be-8640-0d9fd2f561ae",
    	"status_code": 200
    }
    ```

    A successful API call completes the secret rotation and results in the following updates:

    * The M2M Client's `client_secret` from **Steps 1 and 2** will be invalidated.
    * The M2M Client's `client_secret` from **Steps 1 and 2** will be replaced by the `next_client_secret`. To confirm, check the M2M Client's `client_secret_last_four` updated value.
    * The M2M Client's `next_client_secret_last_four` will be set back to `null`.
  </Step>

  <Step title="Cancel the secret rotation (optional)">
    If for any reason after **Step 2** you need to stop or revert the secret rotation process, call the [Cancel Secret Rotation endpoint](/api-reference/b2b/api/m2m/rotate-secret/cancel-secret-rotation) with the `client_id`.

    ```sh theme={null}
    curl --request POST \
    	--url https://test.stytch.com/v1/m2m/clients/{CLIENT_ID}/secrets/rotate/cancel \
    	-u '{PROJECT_ID}:{SECRET}'
    ```

    ```json theme={null}
    {
    	"m2m_client": {
    		"client_description": "Following the Stytch guide.",
    		"client_id": "m2m-client-test-a50053...",
    		"client_name": "Example client",
    		"client_secret_last_four": "DzJj",
    		"next_client_secret_last_four": null,
    		"scopes": [
    			"read:settings",
    			"update:settings"
    		],
    		"status": "active",
    		"trusted_metadata": {
    			"billing_tier": "standard",
    			"api_version": "v2"
    		}
    	},
    	"request_id": "request-id-test-c50eb06f-69b4-41be-8640-0d9fd2f561ae",
    	"status_code": 200
    }
    ```

    A successful API call cancels the secret rotation and results in the following updates:

    * The M2M Client's `client_secret` from **Steps 1 and 2** will not be updated and will remain valid.
    * The M2M Client's `next_client_secret` and `next_client_secret_last_four` will be invalidated and set back to `null`.
  </Step>
</Steps>

## What's next

Learn how to [import M2M Clients from other platforms like Auth0](/multi-tenant-auth/authentication/m2m/import-clients).

Also, take a look at our comprehensive [M2M Authentication example app tutorial](https://stytch.com/blog/how-to-implement-m2m-authentication-and-authorization-in-node-js-using-stytch/), which includes an open-source [GitHub repo](https://github.com/stytchauth/stytch-m2m-node-example) utilizing the Node.js SDK.