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

> ## Agent Instructions
> Phaseo Gateway base URL: https://api.phaseo.app/v1. Send `Authorization: Bearer $PHASEO_API_KEY` with every request.
> Model IDs look like `provider/model`, for example `openai/gpt-6-astra`. Do not guess IDs: list them with `GET /v1/models` or check https://phaseo.app/models. `phaseo/free` routes to an available free model and needs no wallet balance.
> For new text integrations prefer `POST /v1/responses`. `POST /v1/chat/completions` (OpenAI format) and `POST /v1/messages` (Anthropic format) suit existing code.
> The full API contract is https://phaseo.app/docs/openapi/v1/openapi.yaml. Official SDKs: `@phaseo/sdk` (TypeScript) and `phaseo` (Python), plus Go, C#, PHP, Ruby and Rust.
> Search these docs over MCP at https://phaseo.app/docs/mcp, and install Phaseo skills with `npx skills add https://phaseo.app/docs`. If a page is wrong or out of date, report it with the MCP `submit_feedback` tool.
> Manage Phaseo accounts with the `phaseo` CLI (`npm install -g @phaseo/cli`, then `phaseo login` or `phaseo login --device-code`), the `/v1` Management API or the MCP server at `https://mcp.phaseo.app/mcp?access=manage`. Do not send users to the dashboard for account tasks. A person is still needed for sign-up, approving a sign-in, paying the first top-up on the checkout link that `phaseo credits add` returns when no card is saved, confirming each saved-card top-up from the emailed link, and account security (password, MFA, passkeys). Create API keys with `phaseo keys create --name <name> --json`; never guess one. Credit top-ups need `phaseo login --scopes billing:write` first. Task map: https://phaseo.app/docs/v1/developers/manage-from-an-agent.md.

# Rotate notification webhook secret

> Generates a new signing secret for a custom webhook destination and returns it once. Destinations created before signing get their first secret this way. Later deliveries are signed with the new secret and the previous secret stops being used.

> [!NOTE]
>
> Workspace notification administration requires an owner or admin identity and the matching settings scope. Destination targets are encrypted and never returned.


## OpenAPI

````yaml openapi/v1/openapi.yaml POST /notifications/destinations/{id}/rotate-secret
openapi: 3.0.3
info:
  title: Phaseo Gateway API
  description: >-
    A gateway API for accessing various AI models with OpenAI-compatible
    endpoints.
  version: 1.0.0
  contact:
    name: Phaseo
    url: https://phaseo.app
    email: danielbutler500@gmail.com
servers:
  - url: https://api.phaseo.app/v1
    description: Global routing
security:
  - BearerAuth: []
tags:
  - name: Gateway
    description: Core Phaseo Gateway operations.
paths:
  /notifications/destinations/{id}/rotate-secret:
    post:
      tags:
        - Gateway
      summary: Rotate a notification webhook signing secret
      description: >-
        Generates a new signing secret for a custom webhook destination and
        returns it once. Destinations created before signing get their first
        secret this way. Later deliveries are signed with the new secret and the
        previous secret stops being used.
      operationId: rotateWorkspaceNotificationDestinationSecret
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Signing secret rotated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceNotificationDestinationResponse'
        default:
          description: Request failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    WorkspaceNotificationDestinationResponse:
      type: object
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/WorkspaceNotificationDestination'
      additionalProperties: false
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        ok:
          type: boolean
          example: false
        error:
          description: >-
            The error object (`code`, `message`, `type`, `param` and optional
            `metadata`) that OpenAI-compatible SDKs read. Earlier responses
            returned the code string here; it is now also returned as top-level
            `code`.
          oneOf:
            - type: string
            - $ref: '#/components/schemas/ErrorObject'
          example:
            code: validation_error
            message: 'Unknown parameter: foo'
            type: invalid_request_error
            param: foo
        code:
          type: string
          description: The error code, the same value as `error.code`.
          example: validation_error
        message:
          type: string
          example: Human-readable error message
        description:
          type: string
          example: Additional error details.
        generation_id:
          type: string
          example: G-abc123
        status_code:
          type: integer
          example: 502
        error_type:
          type: string
          enum:
            - user
            - system
          example: system
        error_origin:
          type: string
          enum:
            - user
            - gateway
            - upstream
          example: upstream
        reason:
          type: string
          example: all_candidates_failed
        attempt_count:
          type: integer
          example: 2
        failed_providers:
          type: array
          items:
            type: string
          example:
            - google-ai-studio
            - openai
        failed_statuses:
          type: array
          items:
            type: integer
          example:
            - 403
            - 429
        upstream_error:
          $ref: '#/components/schemas/ErrorUpstreamError'
        failure_sample:
          type: array
          items:
            $ref: '#/components/schemas/ErrorFailureSampleItem'
        provider_failure_diagnostics:
          $ref: '#/components/schemas/ErrorProviderFailureDiagnostics'
        routing_diagnostics:
          $ref: '#/components/schemas/ErrorRoutingDiagnostics'
        provider_candidate_diagnostics:
          $ref: '#/components/schemas/ErrorProviderCandidateDiagnostics'
        provider_enablement:
          $ref: '#/components/schemas/ErrorProviderEnablementDiagnostics'
        missing_pricing_providers:
          type: array
          items:
            type: string
        provider_payment_required_provider:
          type: string
          example: openai
        provider_payment_required_support_notice:
          type: string
          example: >-
            Our upstream provider billing appears to be unavailable. If this
            persists, contact support.
        details:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    WorkspaceNotificationDestination:
      type: object
      required:
        - id
        - name
        - type
        - target_preview
        - status
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        type:
          $ref: '#/components/schemas/WorkspaceNotificationDestinationType'
        target_preview:
          type: string
        status:
          type: string
          enum:
            - active
            - disabled
        has_signing_secret:
          type: boolean
          description: >-
            Whether deliveries are signed with x-phaseo-signature. Only custom
            webhook destinations are signed; ones created before signing stay
            unsigned until a secret is generated.
        signing_secret_rotated_at:
          type: string
          format: date-time
          nullable: true
          description: When the current signing secret was generated.
        signing_secret:
          type: string
          description: >-
            The webhook signing secret. Returned only when a custom webhook
            destination is created or its secret is rotated; store it securely.
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
      additionalProperties: false
    ErrorObject:
      type: object
      description: >-
        A gateway error in the shape OpenAI's SDKs read. `type` is set from the
        HTTP status: invalid_request_error for most 4xx, authentication_error
        (401), insufficient_quota (402), permission_error (403), not_found_error
        (404), rate_limit_error (429), service_unavailable (503), overloaded
        (529) and server_error for other 5xx.
      required:
        - code
        - message
        - type
      properties:
        code:
          type: string
          description: Machine-readable error code.
          example: validation_error
        message:
          type: string
          description: Human-readable explanation of the failure.
          example: 'Unknown parameter: foo'
        type:
          type: string
          description: The error type, following OpenAI's documented error types.
          enum:
            - invalid_request_error
            - authentication_error
            - permission_error
            - not_found_error
            - rate_limit_error
            - insufficient_quota
            - server_error
            - service_unavailable
            - overloaded
          example: invalid_request_error
        param:
          type: string
          nullable: true
          description: The request parameter that caused the error, when known.
          example: foo
        metadata:
          type: object
          description: >-
            Structured detail also returned at the top level, such as the
            failing provider, `reason`, `failed_statuses`, `retry_after_seconds`
            or `upstream_error`.
          additionalProperties: true
      additionalProperties: true
    ErrorUpstreamError:
      type: object
      properties:
        code:
          type: string
          nullable: true
          example: PERMISSION_DENIED
        message:
          type: string
          nullable: true
          example: The caller does not have permission.
        description:
          type: string
          nullable: true
        param:
          type: string
          nullable: true
    ErrorFailureSampleItem:
      type: object
      properties:
        provider:
          type: string
          nullable: true
        type:
          type: string
          nullable: true
        status:
          type: integer
          nullable: true
        upstream_error_code:
          type: string
          nullable: true
        upstream_error_message:
          type: string
          nullable: true
        upstream_error_description:
          type: string
          nullable: true
        upstream_error_param:
          type: string
          nullable: true
        upstream_payload_preview:
          type: string
          nullable: true
        retryable:
          type: boolean
          nullable: true
      additionalProperties: true
    ErrorProviderFailureDiagnostics:
      type: object
      properties:
        category:
          type: string
          enum:
            - credentials_not_configured
            - credentials_invalid_or_forbidden
            - provider_access_missing
            - region_or_project_restriction
            - model_unavailable_for_endpoint
            - rate_limited
            - server_error
        hint:
          type: string
        provider:
          type: string
          nullable: true
    ErrorRoutingDiagnostics:
      type: object
      properties:
        filterStages:
          type: array
          items:
            type: object
            properties:
              stage:
                type: string
              beforeCount:
                type: integer
              afterCount:
                type: integer
              droppedProviders:
                type: array
                items:
                  type: object
                  properties:
                    providerId:
                      type: string
                      nullable: true
                    reason:
                      type: string
                      nullable: true
                  additionalProperties: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderCandidateDiagnostics:
      type: object
      properties:
        totalProviders:
          type: integer
        supportsEndpointCount:
          type: integer
        candidateCount:
          type: integer
        droppedUnsupportedEndpoint:
          type: array
          items:
            type: string
        droppedMissingAdapter:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              endpoint:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    ErrorProviderEnablementDiagnostics:
      type: object
      properties:
        capability:
          type: string
        providersBefore:
          type: array
          items:
            type: string
        providersAfter:
          type: array
          items:
            type: string
        dropped:
          type: array
          items:
            type: object
            properties:
              providerId:
                type: string
                nullable: true
              reason:
                type: string
                nullable: true
            additionalProperties: true
      additionalProperties: true
    WorkspaceNotificationDestinationType:
      type: string
      enum:
        - email
        - discord
        - discord_webhook
        - slack
        - microsoft_teams
        - custom_webhook
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication

````

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