Vonage Secret Management API

openapi: 3.2.0
info:
  title: Vonage Secret Management API
  version: 1.0.4
  contact:
    name: Vonage Developer Relations
    email: devrel@vonage.com
    url: https://developer.vonage.com/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://www.vonage.com/legal/communications-apis/terms-of-use/
  x-metaDescription: Find quick answers to questions about the Vonage Account API in this reference guide. Learn more in Vonage's API documentation.
  x-metaTitle: Vonage Account API Reference | Vonage API Documentation
  description: 'Operations tagged Secret Management across 2 of this provider''s published API definitions: vonage-account-openapi.json, vonage-account-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://rest.nexmo.com
  description: Rest Server
security:
- basicAuth: []
tags:
- name: Secret Management
  description: 'Many of the Vonage APIs are accessed using an API key and secret. It is recommended that you change or "rotate" your secrets from time to time for security purposes. This section provides the API interface for achieving this.

    Note: to work on secrets for your secondary accounts, you may authenticate with your primary credentials and supply the secondary API keys as URL parameters to these API endpoints.'
paths:
  /accounts/{api_key}/secrets:
    get:
      description: Retrieve API Secrets
      operationId: retrieveAPISecrets
      tags:
      - Secret Management
      parameters:
      - $ref: '#/components/parameters/APIKey'
      responses:
        '200':
          $ref: '#/components/responses/AccountsSecretsPageResponse'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      summary: Retrieve API secrets
      x-summary-source: derived
    post:
      description: Create API Secret
      operationId: createAPISecret
      tags:
      - Secret Management
      parameters:
      - $ref: '#/components/parameters/APIKey'
      requestBody:
        $ref: '#/components/requestBodies/CreateSecretRequest'
      responses:
        '201':
          $ref: '#/components/responses/CreateAccountSecretResponse'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      summary: Create API secret
      x-summary-source: derived
    servers:
    - url: https://rest.nexmo.com
      description: Rest Server
  /accounts/{api_key}/secrets/{secret_id}:
    get:
      description: Retrieve one API Secret
      operationId: retrieveAPISecret
      tags:
      - Secret Management
      parameters:
      - $ref: '#/components/parameters/APIKey'
      - $ref: '#/components/parameters/secretId'
      responses:
        '200':
          $ref: '#/components/responses/AccountSecretResponse'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      summary: Retrieve API secret
      x-summary-source: derived
    delete:
      description: Revoke an API Secret
      operationId: revokeAPISecret
      tags:
      - Secret Management
      parameters:
      - $ref: '#/components/parameters/APIKey'
      - $ref: '#/components/parameters/secretId'
      responses:
        '204':
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          description: Revoked secret response (without body content)
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/CannotRevokeSecretResponse'
        '404':
          $ref: '#/components/responses/404'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
      summary: Revoke API secret
      x-summary-source: derived
    servers:
    - url: https://rest.nexmo.com
      description: Rest Server
components:
  responses:
    AccountSecretResponse:
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      description: API secret response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SecretInfo'
    AccountsSecretsPageResponse:
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      description: The list of your current API secrets
      content:
        application/json:
          schema:
            properties:
              _links:
                $ref: '#/components/schemas/_links'
              _embedded:
                type: object
                description: The single `secrets` key returns an array of API secrets
                properties:
                  secrets:
                    type: array
                    description: Array of API secrets
                    items:
                      $ref: '#/components/schemas/SecretInfo'
    CannotRevokeSecretResponse:
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      description: Operation forbidden by permissions or because this is the only API secret and you are required to have at least one.
      content:
        application/json:
          schema:
            properties:
              type:
                type: string
                description: URL for further information
                example: https://developer.nexmo.com/api-errors/account/secret-management#delete-last-secret
              title:
                type: string
                description: Description of the error
                example: Secret Deletion Forbidden
              detail:
                type: string
                description: More detail regarding this error
                example: Can not delete the last secret. The account must always have at least 1 secret active at any time
              instance:
                type: string
                description: Internal Trace ID
                example: bf0ca0bf927b3b52e3cb03217e1a1ddf
    BadRequestResponse:
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      description: Secret not created
      content:
        application/problem+json:
          schema:
            type: object
            properties:
              type:
                type: string
                description: URL for further information
                example: https://developer.nexmo.com/api-errors/account/secret-management#validation
              title:
                type: string
                description: Description of the error
                example: Bad Request
              detail:
                type: string
                description: More detail regarding this error, including the API key supplied
                example: The request failed due to secret validation errors
              instance:
                type: string
                description: Internal Trace ID
                example: bf0ca0bf927b3b52e3cb03217e1a1ddf
              invalid_parameters:
                type: array
                description: Array of the parameters that are considered invalid, and explanations of why
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Field name
                      example: secret
                    reason:
                      type: string
                      description: Explanation of why parameter is considered invalid
                      example: Does not meet complexity requirements
    '404':
      description: Not Found
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    '500':
      description: Internal error
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    CreateAccountSecretResponse:
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      description: Secret created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SecretInfo'
    '401':
      description: Authentication failure
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            oneOf:
            - description: Missing or Invalid Credentials
              type: object
              required:
              - type
              - title
              - instance
              properties:
                type:
                  type: string
                  description: Link to error / remediation options
                  example: https://developer.vonage.com/api-errors/#unathorized
                title:
                  type: string
                  description: Generic error message
                  example: You did not provide correct credentials.
                detail:
                  type: string
                  description: Additional information about the error
                  example: Check that you're using the correct credentials, and that your account has this feature enabled
                instance:
                  type: string
                  description: Internal Trace ID
                  example: bf0ca0bf927b3b52e3cb03217e1a1ddf
            - description: Invalid Application Type
              type: object
              required:
              - type
              - title
              - instance
              properties:
                type:
                  type: string
                  description: Link to error / remediation options
                  example: https://developer.vonage.com/api-errors/#unprovisioned
                title:
                  type: string
                  description: Generic error message
                  example: The crendentials provided do not have access to the requested product
                detail:
                  type: string
                  description: Additional information about the error
                  example: Check your API key is correct and has been whitelisted
                instance:
                  type: string
                  description: Internal Trace ID
                  example: bf0ca0bf927b3b52e3cb03217e1a1ddf
    '429':
      description: Too Many Requests
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  requestBodies:
    CreateSecretRequest:
      content:
        application/json:
          schema:
            type: object
            required:
            - secret
            properties:
              secret:
                description: 'The new secret must follow these rules:


                  * minimum 8 characters

                  * maximum 25 characters

                  * minimum 1 lower case character

                  * minimum 1 upper case character

                  * minimum 1 digit

                  '
                type: string
                example: example-4PI-secret
  schemas:
    SelfLink:
      type: object
      description: Link to the current resource (always required in HAL)
      required:
      - self
      properties:
        self:
          $ref: '#/components/schemas/HalLink'
    _links:
      type: object
      description: HAL Links object
      allOf:
      - $ref: '#/components/schemas/SelfLink'
    ErrorResponse:
      type: object
      description: Base error response following RFC 7807
      required:
      - type
      - title
      - instance
      properties:
        type:
          type: string
          description: Link to error / remediation options
          example: https://developer.vonage.com/api-errors
        title:
          type: string
          description: Generic error message
          example: An error occurred
        detail:
          type: string
          description: Additional information about the error
          example: More details about what went wrong
        instance:
          type: string
          description: Internal Trace ID
          example: bf0ca0bf927b3b52e3cb03217e1a1ddf
    HalLink:
      type: object
      description: A single HAL link object
      required:
      - href
      properties:
        href:
          type: string
          description: The URL for the resource
          example: https://api.vonage.com/v1/resources/abc123
        templated:
          type: boolean
          description: Indicates if the href is a URI template
          example: false
        type:
          type: string
          description: Media type hint for the target resource
          example: application/json
        name:
          type: string
          description: Secondary key for selecting link objects
          example: resource-name
        title:
          type: string
          description: Human-readable title for the link
          example: Resource Title
    SecretInfo:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/_links'
        id:
          type: string
          description: Secret ID
          example: ad6dc56f-07b5-46e1-a527-85530e625800
        created_at:
          type: string
          description: Creation date/time for this secret
          example: '2017-03-02T16:34:49Z'
  parameters:
    APIKey:
      name: api_key
      in: path
      description: The API key to manage secrets for
      example: abcd1234
      required: true
      schema:
        type: string
    secretId:
      name: secret_id
      in: path
      description: ID of the API Secret
      example: 01234567-aaaa-bbbb-cccc-defdefdefdef
      required: true
      schema:
        type: string
  headers:
    Retry-After:
      description: Seconds until next request allowed
      schema:
        type: integer
        example: 15
    X-RateLimit-Remaining:
      description: Remaining requests
      schema:
        type: integer
        example: 5
    X-RateLimit-Reset:
      description: Unix timestamp when limit resets
      schema:
        type: integer
        example: 1769182705723
    X-Request-Id:
      description: A unique identifier for the request, used for tracking and debugging
      schema:
        type: string
        format: uuid
        example: f94b4e56-604e-07e5-e5ad-5a7228618f81
    X-RateLimit-Limit:
      description: Request limit per hour
      schema:
        type: integer
        example: 30
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
x-refined-from:
- vonage-account-openapi.json
- vonage-account-openapi.yml
x-errors:
  validation:
    description: The provided payload is invalid
    resolution: 'Modify your request to provide a valid payload.

      * Minimum 8 characters

      * Maximum 25 characters

      * Minimum 1 lower case character

      * Minimum 1 upper case character

      * Minimum 1 digit

      '
    link:
      text: View API reference
      url: /api/account#createAPISecret
  delete-last-secret:
    description: You can not delete your only API secret
    resolution: Add another API secret before deleting this one