---
title: "Roll endpoint secret"
method: PUT
path: "/v1/projects/{projectID}/endpoints/{endpointID}/expire_secret"
tags: ["Endpoints"]
---

# Roll endpoint secret

`PUT /v1/projects/{projectID}/endpoints/{endpointID}/expire_secret`

This endpoint expires and re-generates the endpoint secret.

## Path parameters

- `projectID` string, required
- `endpointID` string, required

## Request body

- ModelsExpireSecret
  - `expiration` integer — Amount of time to wait before expiring the old endpoint secret. If AdvancedSignatures is turned on for the project, signatures for both secrets will be generated up until the old signature is expired.
  - `secret` string — New Endpoint secret value.

## Response `200`

OK

- object
  - `message` string
  - `status` boolean
  - `data` ModelsEndpointResponse
    - `advanced_signatures` boolean
    - `authentication` DatastoreEndpointAuthentication
      - `api_key` DatastoreApiKey
        - `header_name` string
        - `header_value` string
      - `basic_auth` DatastoreBasicAuth
        - `password` string
        - `username` string
      - `oauth2` DatastoreOAuth2
        - `audience` string
        - `authentication_type` 'shared_secret' | 'client_assertion' | ''
        - `client_id` string
        - `client_secret` string — Encrypted at rest
        - `expiry_time_unit` 'seconds' | 'milliseconds' | 'minutes' | 'hours' | ''
        - `field_mapping` DatastoreOAuth2FieldMapping
          - `access_token` string — Field name for access token (e.g., "accessToken", "access_token", "token")
          - `expires_in` string — Field name for expiry time (e.g., "expiresIn", "expires_in", "expiresAt")
          - `token_type` string — Field name for token type (e.g., "tokenType", "token_type")
        - `grant_type` string
        - `issuer` string
        - `scope` string
        - `signing_algorithm` string
        - `signing_key` DatastoreOAuth2SigningKey
          - `crv` string — EC (Elliptic Curve) key fields
          - `d` string — Private key (EC only)
          - `dp` string — RSA first factor CRT exponent (RSA private key only)
          - `dq` string — RSA second factor CRT exponent (RSA private key only)
          - `e` string — RSA public exponent (RSA only)
          - `kid` string — Key ID
          - `kty` string — Key type: "EC" or "RSA"
          - `n` string — RSA key fields
          - `p` string — RSA first prime factor (RSA private key only)
          - `q` string — RSA second prime factor (RSA private key only)
          - `qi` string — RSA first CRT coefficient (RSA private key only)
          - `x` string — X coordinate (EC only)
          - `y` string — Y coordinate (EC only)
        - `subject` string
        - `url` string
      - `type` 'api_key' | 'oauth2' | 'basic_auth' | ''
    - `cb_state` string, nullable — CBState is the circuit breaker state ("open", "half-open", "closed") so the UI can reflect a tripped breaker on the endpoint status. Nil when CB is off/unlicensed or has no sample for this endpoint.
    - `content_type` string
    - `created_at` string
    - `deleted_at` string, nullable
    - `description` string
    - `events` integer
    - `failure_count` integer, nullable
    - `failure_rate` number, nullable — FailureRate is the circuit breaker's rolling failure rate for this endpoint. It is a pointer so the API can return null when no rate was computed (circuit breaker feature off, or sampler not running), distinct from a genuine 0%.
    - `http_timeout` integer
    - `mtls_client_cert` DatastoreMtlsClientCert
      - `client_cert` string — ClientCert is the client certificate PEM string
      - `client_key` string — ClientKey is the client private key PEM string
    - `name` string
    - `owner_id` string
    - `period_failure_rate` number, nullable — PeriodFailureRate is the period failure rate from event_deliveries, (Failure+Retry)/(Success+Failure+Retry). Retry counts as failed-so-far. Nil when the range has no counted deliveries; sibling counts are transient.
    - `project_id` string
    - `rate_limit` integer
    - `rate_limit_duration` integer
    - `retry_count` integer, nullable
    - `secrets` DatastoreSecret[]
      - `created_at` string
      - `deleted_at` string, nullable
      - `expires_at` string, nullable
      - `uid` string
      - `updated_at` string
      - `value` string
    - `slack_webhook_url` string
    - `status` 'active' | 'inactive' | 'paused' | ''
    - `success_count` integer, nullable
    - `support_email` string
    - `uid` string
    - `updated_at` string
    - `url` string

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found

---

[API](https://skmtc.net/getconvoy/apis/convoy-api-reference.md) · [All operations](https://skmtc.net/getconvoy/apis/convoy-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getconvoy/convoy-api-reference/versions/9d68b6f4aead/schema)