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

# Stop Previous API Key Value

> Ends a rotation's overlap early: the old value of one of your public or secret keys stops working now. Use it once your apps use the new value, or when the old value leaked. Nothing changes when no old value is still working.



## OpenAPI

````yaml /api-reference/openapi.json delete /v1/projects/api-keys/{apiKeyId}/previous
openapi: 3.0.1
info:
  title: Hamsa API
  description: >-
    The Hamsa API: voice agents and their calls, phone numbers, batch calls and
    knowledge bases; speech to text, text to speech, voices and AI content.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.tryhamsa.com
security: []
paths:
  /v1/projects/api-keys/{apiKeyId}/previous:
    delete:
      summary: Stop the old value of a rotated key
      description: >-
        Ends a rotation's overlap early: the old value of one of your public or
        secret keys stops working now. Use it once your apps use the new value,
        or when the old value leaked. Nothing changes when no old value is still
        working.
      parameters:
        - in: query
          name: projectId
          required: true
          description: >-
            ID of the project. With an API key, it must be the key's own
            project.
          schema:
            type: string
            format: uuid
            example: fbb9e8b2-2dbb-40f9-a051-9404624e3247
        - in: path
          name: apiKeyId
          required: true
          description: The key's `id` or `ref`. Only the key's owner can do this.
          schema:
            type: string
            example: key_9f2c4e1a7b3d5f6081a2c3d4e5f60718
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: success
                  data:
                    $ref: '#/components/schemas/ApiKey'
        '400':
          description: Invalid request, or a legacy key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyError'
        '401':
          description: 'Unauthorized: missing or invalid API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '403':
          description: >-
            A limited key can't manage API keys (`ApiKeyScopeRouteNotAllowed`,
            "This route needs a full-access API key."). Refused: a public key
            can only create call tokens (`PublicKeyMintOnly`), a secret key
            cannot be used from a browser (`SecretKeyInBrowser`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorSchema'
        '404':
          description: Not one of your keys in this project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyError'
        '500':
          description: Server Side Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyError'
      security:
        - ApiKeyAuth: []
components:
  schemas:
    ApiKey:
      type: object
      description: >-
        An API key. Never contains a secret key's value, except `secret` in the
        response that creates or rotates it.
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Key ID. For a `LEGACY` key this is also the key value: keep it
            secret.
          example: 3f6c1a2e-8b4d-4e9a-9c1f-2a7d5e8b0c34
        name:
          type: string
          description: Key name, unique in the project.
          example: Backend server
        kind:
          type: string
          enum:
            - LEGACY
            - PUBLIC
            - SECRET
          description: >-
            `SECRET` (`sk_...`): for servers. The value is shown once, in the
            response that creates or rotates the key; requests that carry an
            `Origin` header (browsers) are refused. `PUBLIC` (`pk_...`): for web
            pages and apps. It can only create call tokens (`POST
            /v1/voice-agents/call-token`), for one `environment`, and its value
            can be read again at any time. `LEGACY`: the older kind, whose key
            ID is also its value. New legacy keys are being retired: when they
            are turned off, creating one returns `LegacyApiKeysRetired`.
          example: SECRET
        type:
          type: string
          enum:
            - ROOT
            - SCOPED
          description: >-
            `ROOT`: everything your role in the project allows (scopes `["*"]`).
            `SCOPED`: only the `scopes` you list, and never more than your role
            allows. Public keys are always `SCOPED` with `["agents:call"]`.
          example: SCOPED
        scopes:
          type: array
          items:
            type: string
          description: >-
            Saved scopes (presets expanded). `["*"]` for a `ROOT` key. An older
            `ROOT` key may show `[]`; it still has full access.
          example:
            - agents:read
            - agents:call
            - phone_numbers:read
            - phone_numbers:update
            - call_history:read
            - call_history:monitor
        allowedDomains:
          type: array
          items:
            type: string
          description: 'Hostnames the key may be used from. Empty: any.'
          example:
            - example.com
        environment:
          type: string
          nullable: true
          enum:
            - dev
            - staging
            - prod
          description: >-
            Public keys only: the environment their call tokens run. `null` for
            other kinds.
          example: null
        publicValue:
          type: string
          description: 'Public keys only: the full `pk_...` value.'
          example: pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
        secretLast4:
          type: string
          description: >-
            Secret keys only: the last 4 characters of the value, to tell keys
            apart.
          example: xxxx
        agentIds:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Agents the key may create call tokens for (agents of this project).
            Empty or omitted: every agent.
          example:
            - 8a1d2c3b-4e5f-4a6b-9c7d-0e1f2a3b4c5d
        expiredAt:
          type: string
          format: date-time
          nullable: true
          description: 'When the key expires (end of that day). `null`: never.'
          example: '2027-12-31T23:59:59.999Z'
        previousValidUntil:
          type: string
          format: date-time
          nullable: true
          description: >-
            After a rotation: until when the old value still works. `null` when
            no old value works.
          example: null
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
          description: When the current value was last used (public and secret keys).
          example: '2026-11-03T09:15:00.000Z'
        previousLastUsedAt:
          type: string
          format: date-time
          nullable: true
          description: When the old value was last used, after a rotation.
          example: null
        ref:
          type: string
          nullable: true
          description: >-
            Non-secret key ID (`key_` + 32 hex characters), safe to share and
            log.
          example: key_9f2c4e1a7b3d5f6081a2c3d4e5f60718
        isDefault:
          type: boolean
          description: '`true` for the project''s Default key or a member''s default key.'
          example: false
        createdAt:
          type: string
          format: date-time
          example: '2026-11-03T09:15:00.000Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-11-03T09:15:00.000Z'
        status:
          type: string
          enum:
            - VALID
            - EXPIRED
          description: Stored validity of the key.
          example: VALID
        isValid:
          type: boolean
          description: '`false` when the key is disabled or expired.'
          example: true
        projectId:
          type: string
          format: uuid
          nullable: true
          example: fbb9e8b2-2dbb-40f9-a051-9404624e3247
        secret:
          type: string
          description: >-
            Secret keys only, and only in the response that creates or rotates
            the key: the full `sk_...` value. It is not stored and cannot be
            shown again, so save it now.
          example: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ApiKeyError:
      type: object
      description: Error returned by the API key routes.
      properties:
        code:
          type: integer
          enum:
            - 5400
            - 5403
            - 5404
            - 5409
            - 5500
          description: 'Service error code: 5000 + the HTTP status.'
          example: 5409
        message:
          type: string
          description: What went wrong, in English.
          example: This API key was already revoked.
        messageKey:
          type: string
          enum:
            - PermissionDenied
            - ApiKeyNotFound
            - ApiKeyExpired
            - ApiKeyAlreadyRevoked
            - LegacyApiKeysRetired
            - DefaultApiKeyProtected
            - LastApiKeyProtected
            - SomethingWentWrong
          description: >-
            Stable error key to branch on. `SomethingWentWrong` for errors
            without their own key (read `message`).
          example: ApiKeyAlreadyRevoked
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors: `action` (for example `api_keys:revoke`) on
            `PermissionDenied`, `reason: "DISABLED_BY_OTHER"` and `disabledBy`
            when you try to enable your own key that someone else disabled,
            `expired` on `LastApiKeyProtected`.
          example:
            action: api_keys:revoke
    ErrorSchema:
      type: object
      properties:
        code:
          type: integer
          description: >-
            Service error code: the HTTP status with a service prefix (for
            example `8404`). Missing when the service has no code for that
            status.
          example: 8404
        message:
          type: string
          description: >-
            What went wrong. Some services (calls and recordings) put the error
            key here, for example `CallNotFoundOrUnavailable`, and send no
            `messageKey`.
          example: Policy not found!
        messageKey:
          type: string
          description: >-
            Stable key for the error, safe to match on in code. Not returned by
            every service.
          example: PolicyNotFound
        params:
          type: object
          additionalProperties: true
          description: >-
            Details for some errors (for example `reason`). Not returned by
            every service.
          example:
            reason: NO_DRAFT
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Pass the API key in the Authorization header, You need to put Token
        keyword before the API key. e.g. 'Authorization: Token <api-key>'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.