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

# Request a sandbox-only agent credential



## OpenAPI

````yaml /api-reference/openapi.json post /v1/agent-credentials
openapi: 3.0.0
info:
  title: WattShift API
  description: An API for the WattShift Service (https://wattshift.com/partners)
  version: '1.0'
  contact: {}
servers: []
security: []
tags: []
paths:
  /v1/agent-credentials:
    post:
      tags:
        - agent-credentials
      summary: Request a sandbox-only agent credential
      operationId: requestAgentSandboxCredential
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentCredentialRequestDto'
            example:
              agent: claude-code
              client: cli
              organization_name: Example Energy Co
              user_name: Avery Developer
              assignment: Prototype bill impact calculations for a customer dashboard
              tech_stack:
                - typescript
                - node
              use_case: Evaluate WattShift bill impact endpoints in sandbox
              user_email: developer@example.com
              company: Example Energy Co
              requested_scopes:
                - calculate
                - homes
              requested_environment: sandbox
              requested_ttl_seconds: 86400
      responses:
        '200':
          description: Sandbox credential issuance outcome.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentCredentialResponseDto'
              example:
                outcome: issued
                credential: wsk_agent_example_token
                credential_id: ws_agent_cred_123456789
                key_prefix: wsk_agent
                request_id: ws_request_123456789
                credential_request_id: ws_cred_request_123456789
                expires_at: '2025-01-03T12:00:00.000Z'
                scopes:
                  - calculate
                  - homes
                environment: sandbox
                production_access: false
                revocation_method: POST
                revocation_path: /v1/agent-credentials/ws_agent_cred_123456789/revoke
                next_steps: >-
                  Store the credential securely and send it as the x-ws-api-key
                  header on sandbox requests.
components:
  schemas:
    CreateAgentCredentialRequestDto:
      type: object
      properties:
        agent:
          type: string
          maxLength: 128
        client:
          type: string
          maxLength: 128
        organization_name:
          type: string
          minLength: 1
          maxLength: 255
        user_name:
          type: string
          minLength: 1
          maxLength: 255
        assignment:
          type: string
          minLength: 10
          maxLength: 4000
        tech_stack:
          type: array
          maxItems: 20
          items:
            type: string
            maxLength: 64
          default: []
        use_case:
          type: string
          maxLength: 128
        device_segment:
          type: string
          maxLength: 128
        project:
          type: string
          maxLength: 128
        user_email:
          type: string
          format: email
        company:
          type: string
          maxLength: 255
        requested_scopes:
          type: array
          minItems: 1
          maxItems: 20
          items:
            type: string
            maxLength: 128
        requested_environment:
          type: string
          enum:
            - sandbox
            - production
          default: sandbox
        requested_ttl_seconds:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        docs_context:
          type: string
          format: uri
          maxLength: 2048
      required:
        - organization_name
        - user_name
        - assignment
        - requested_scopes
    AgentCredentialResponseDto:
      type: object
      properties:
        outcome:
          type: string
          enum:
            - issued
            - needs_more_info
            - rate_limited
            - production_denied
        credential:
          type: string
        credential_id:
          type: string
        key_prefix:
          type: string
        request_id:
          type: string
        credential_request_id:
          type: string
        expires_at:
          type: string
          format: date-time
        scopes:
          type: array
          items:
            type: string
          default: []
        environment:
          type: string
          enum:
            - sandbox
        production_access:
          type: boolean
        revocation_method:
          type: string
          enum:
            - POST
        revocation_path:
          type: string
        retry_after_seconds:
          type: integer
          minimum: 0
          exclusiveMinimum: true
        next_steps:
          type: string
      required:
        - outcome
        - request_id
        - credential_request_id
        - environment
        - production_access
        - next_steps

````