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

# Provision an Internal Credential

> Issue a server-generated internal credential for an agent. Requires a provider-authenticated principal with agent update permission; agent credentials are refused. 201 returns a newly issued credential. 200 returns the same credential again when it was issued within the replay window, for a caller that lost the response. Otherwise an existing credential yields 409 unless `replace` is true, which issues a new credential and revokes every existing internal credential of the agent. A replacement with `replacement_idempotency_key` is made once: a later request with the same agent and key returns the same credential with 200 while it has not been revoked and is within the replacement replay window, and yields 409 otherwise or when the key was used for a different agent.



## OpenAPI

````yaml https://agentex.dev-sgp.scale.com/openapi.json post /agents/{agent_id}/internal-key
openapi: 3.1.0
info:
  title: Agentex API
  version: 0.1.0
servers: []
security: []
paths:
  /agents/{agent_id}/internal-key:
    post:
      tags:
        - Agents
      summary: Provision an Internal Credential
      description: >-
        Issue a server-generated internal credential for an agent. Requires a
        provider-authenticated principal with agent update permission; agent
        credentials are refused. 201 returns a newly issued credential. 200
        returns the same credential again when it was issued within the replay
        window, for a caller that lost the response. Otherwise an existing
        credential yields 409 unless `replace` is true, which issues a new
        credential and revokes every existing internal credential of the agent.
        A replacement with `replacement_idempotency_key` is made once: a later
        request with the same agent and key returns the same credential with 200
        while it has not been revoked and is within the replacement replay
        window, and yields 409 otherwise or when the key was used for a
        different agent.
      operationId: provision_internal_key_agents__agent_id__internal_key_post
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
            title: Agent Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProvisionInternalKeyRequest'
      responses:
        '200':
          description: >-
            Replay of a recently issued internal credential, or of the
            credential a replacement with the same `replacement_idempotency_key`
            issued
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisionInternalKeyResponse'
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProvisionInternalKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ProvisionInternalKeyRequest:
      properties:
        replace:
          type: boolean
          title: Replace
          description: >-
            Issue a new credential and revoke every existing internal credential
            of the agent in the same transaction. Pods still holding a revoked
            credential stop authenticating immediately, so plan a restart with
            the new value. Without this, an existing credential yields 409
            unless it was issued within the replay window.
          default: false
        replacement_idempotency_key:
          anyOf:
            - type: string
              maxLength: 64
              minLength: 1
              pattern: ^[A-Za-z0-9._:-]+$
            - type: 'null'
          title: Replacement Idempotency Key
          description: >-
            Requires `replace`. Binds this replacement to a caller-chosen key
            that is unique across all agents, such as a UUID. The first request
            with the key replaces the credential. A later request with the same
            agent and key returns that same credential with 200 and does not
            rotate again, while the credential has not been revoked and is
            within the replacement replay window. Otherwise, and when the key
            was used for a different agent, it yields 409.
      additionalProperties: false
      type: object
      title: ProvisionInternalKeyRequest
      description: >-
        Callers choose only whether to replace; the key value is always
        server-generated.
    ProvisionInternalKeyResponse:
      properties:
        agent_id:
          type: string
          title: Agent Id
        agent_api_key_id:
          type: string
          title: Agent Api Key Id
        agent_api_key:
          type: string
          title: Agent Api Key
          description: Newly issued credential. Persist it before starting the agent.
      type: object
      required:
        - agent_id
        - agent_api_key_id
        - agent_api_key
      title: ProvisionInternalKeyResponse
      description: First-issuance result, separate from ordinary agent metadata.
    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

````