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

# Test a saved credential

> Check a saved credential's stored secret against its platform. Admin only.

**This is a liveness check.** It proves the stored credentials are still real and that the platform is reachable with them — which is what you want to know after a rotation, or when a flow starts failing. It does NOT prove what the credentials are permitted to do: verifying permissions would mean performing the operations themselves against your live vendor account, which this API will not do.

For permissions, read the credential instead. Every dispatch records what this credential was used for and whether it worked, per service, and `GET /credentials/{credential_id}` returns that record — so you can see what a credential can actually do without running a flow to find out.

Always returns 200 with a result; only an unknown credential id returns 404. On success the credential's last verification time is refreshed. A failure never changes the credential's status, and never records a verification that did not happen. This call spends a little of the provider account's call budget, and is refused rather than made when that budget cannot be checked.



## OpenAPI

````yaml /openapi.json post /credentials/{credential_id}/test
openapi: 3.1.0
info:
  title: GetDialed API
  version: 0.1.0
servers:
  - url: https://api.getdialed.ai/v1
    description: Production
security: []
paths:
  /credentials/{credential_id}/test:
    post:
      tags:
        - credentials
      summary: Test a saved credential
      description: >-
        Check a saved credential's stored secret against its platform. Admin
        only.


        **This is a liveness check.** It proves the stored credentials are still
        real and that the platform is reachable with them — which is what you
        want to know after a rotation, or when a flow starts failing. It does
        NOT prove what the credentials are permitted to do: verifying
        permissions would mean performing the operations themselves against your
        live vendor account, which this API will not do.


        For permissions, read the credential instead. Every dispatch records
        what this credential was used for and whether it worked, per service,
        and `GET /credentials/{credential_id}` returns that record — so you can
        see what a credential can actually do without running a flow to find
        out.


        Always returns 200 with a result; only an unknown credential id returns
        404. On success the credential's last verification time is refreshed. A
        failure never changes the credential's status, and never records a
        verification that did not happen. This call spends a little of the
        provider account's call budget, and is refused rather than made when
        that budget cannot be checked.
      operationId: test_saved_credential_credentials__credential_id__test_post
      parameters:
        - name: credential_id
          in: path
          required: true
          schema:
            type: string
            title: Credential Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestResult'
        '401':
          description: Missing or invalid authentication
          content:
            application/json:
              example:
                detail: Authentication required
        '403':
          description: Caller is authenticated but not an admin
          content:
            application/json:
              example:
                detail: Admin role required
        '404':
          description: >-
            No such credential for this organization (cross-tenant access also
            returns 404)
          content:
            application/json:
              example:
                detail: Credential not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded — retry after the Retry-After header
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
          content:
            application/json:
              example:
                detail: 'Rate limit exceeded: 100 per 1 minute'
      security:
        - APIKeyHeader: []
        - HTTPBearer: []
components:
  schemas:
    TestResult:
      properties:
        success:
          type: boolean
          title: Success
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
        details:
          type: string
          title: Details
        latency_ms:
          type: integer
          title: Latency Ms
        tested_at:
          type: string
          format: date-time
          title: Tested At
      type: object
      required:
        - success
        - error
        - details
        - latency_ms
        - tested_at
      title: TestResult
      description: |-
        Result of a credential test. Returned with HTTP 200 for every test
        outcome, including failures and timeouts — inspect `success` and `error`
        rather than the status code. When `success` is false, `error` is one of:
        AUTH_FAILED, NETWORK, TIMEOUT, RATE_LIMITED, PERMISSION_DENIED,
        INVALID_CREDENTIALS_SHAPE, UNKNOWN. `latency_ms` measures the platform
        round-trip only.
      example:
        details: Authenticated successfully; 3 lists visible
        latency_ms: 412
        success: true
        tested_at: '2026-07-09T18:00:00Z'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    HTTPBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````