Instances

Provision an instance

Creates an instance within the provisioner token's scope and returns its identity and credential. An instance credential cannot call this operation. Providers may also offer other credential issuance paths.

Retries with the same idempotency key and input return the original instance and issued credential, without creating another instance or renewing the credential. Keys are scoped to the provisioner and operation. Reusing a key with different input returns an idempotency conflict.

Optional delivery configures a webhook for the instance. The provisioner supplies a separate signing secret already installed on the receiver. Verification must succeed before creation commits or a credential is issued. Failure returns 422 with code webhook_verification_failed and creates no instance. Unsafe or unsupported delivery configuration returns 400. The signing secret is never returned. Successful retries do not repeat verification. Replaying creation after instance deletion returns 409 with code instance_deleted and must not recreate the instance.

The provider must retain the key and original result for at least seven days (168 hours) after instance creation. Retries do not extend this period. Failed verification can be attempted again with the same key and input. Concurrent same-key attempts must be coalesced and must not commit twice.

Parameters

Request body

application/json · required

{
  "type": "object",
  "additionalProperties": false,
  "description": "Submit an empty object when neither a name nor delivery is supplied.",
  "properties": {
    "instance_name": {
      "type": "string",
      "minLength": 1,
      "description": "A recognisable name for the instance. The provider assigns one if omitted.",
      "examples": [
        "codex-chris-laptop"
      ]
    },
    "delivery": {
      "$ref": "#/components/schemas/WebhookDeliveryInput"
    }
  }
}

{
  "instance_name": "codex-chris-laptop"
}

{
  "delivery": {
    "type": "webhook",
    "url": "https://harness.example.com/aap/events",
    "registration_id": "8246931c-4ce0-4c15-a94a-e9c078ad06e2",
    "signing_secret": "whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
  }
}

Responses

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "instance",
    "credential"
  ],
  "properties": {
    "instance": {
      "$ref": "#/components/schemas/Instance"
    },
    "credential": {
      "$ref": "#/components/schemas/IssuedCredential"
    }
  }
}

{
  "instance": {
    "id": "b29a43a7-1949-4b9f-9d61-b7ae66f85d31",
    "name": "codex-chris-laptop"
  },
  "credential": {
    "token": "example-instance-credential",
    "expires_at": "2026-09-17T12:00:00Z"
  }
}

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "instance",
    "credential"
  ],
  "properties": {
    "instance": {
      "$ref": "#/components/schemas/Instance"
    },
    "credential": {
      "$ref": "#/components/schemas/IssuedCredential"
    }
  }
}

{
  "instance": {
    "id": "b29a43a7-1949-4b9f-9d61-b7ae66f85d31",
    "name": "codex-chris-laptop"
  },
  "credential": {
    "token": "example-instance-credential",
    "expires_at": "2026-09-17T12:00:00Z"
  }
}

Retrieve an instance

Returns the current instance within the provisioner token's scope. Credentials and webhook signing secrets are never included. Deleted instances return 404.

Parameters

Responses

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "name"
  ],
  "properties": {
    "id": {
      "$ref": "#/components/schemas/Identifier"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The name assigned by the provider. A name is not proof of identity."
    },
    "delivery": {
      "$ref": "#/components/schemas/WebhookDelivery",
      "description": "Absent when no receiver is configured. Instance reads never return credentials or signing secrets."
    }
  }
}

{
  "id": "b29a43a7-1949-4b9f-9d61-b7ae66f85d31",
  "name": "codex-chris-laptop",
  "delivery": {
    "type": "webhook",
    "url": "https://harness.example.com/aap/events",
    "registration_id": "8246931c-4ce0-4c15-a94a-e9c078ad06e2"
  }
}

Update an instance

Updates fields within the provisioner token's scope. Omitted fields are unchanged. A supplied delivery object replaces the entire configuration, including its secret, after verification. A failed verification returns 422 with code webhook_verification_failed and changes nothing, including the name. Null delivery removes the receiver and ends outstanding delivery.

Once committed, future attempts for all queued notifications use the new URL and secret, including those for older requests. Notification IDs, bodies and retry deadlines do not change. An attempt already in flight can still reach the old receiver. Replacing delivery does not replay notifications whose delivery has already ended. Deletion must take precedence over an update still being verified.

Idempotency keys are scoped to the provisioner, instance ID and operation. Same-key, same-input retries return the original successful response without repeating verification or reapplying the update. Changed input returns 409. Retain the key and original result for at least seven days after the update commits. Retrying does not renew that period. A replay against a deleted instance returns 404 and cannot restore it. Failed verification can be attempted again with the same key and input. Concurrent same-key attempts must be coalesced and must not commit twice.

Parameters

Request body

application/json · required

{
  "type": "object",
  "additionalProperties": false,
  "minProperties": 1,
  "properties": {
    "instance_name": {
      "type": "string",
      "minLength": 1
    },
    "delivery": {
      "description": "Omit to keep delivery unchanged, replace with a complete object, or use null to remove it.",
      "oneOf": [
        {
          "$ref": "#/components/schemas/WebhookDeliveryInput"
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

{
  "delivery": {
    "type": "webhook",
    "url": "https://harness.example.com/aap/events",
    "registration_id": "8246931c-4ce0-4c15-a94a-e9c078ad06e2",
    "signing_secret": "whsec_AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
  }
}

{
  "instance_name": "codex-chris-desktop"
}

Responses

{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "name"
  ],
  "properties": {
    "id": {
      "$ref": "#/components/schemas/Identifier"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "description": "The name assigned by the provider. A name is not proof of identity."
    },
    "delivery": {
      "$ref": "#/components/schemas/WebhookDelivery",
      "description": "Absent when no receiver is configured. Instance reads never return credentials or signing secrets."
    }
  }
}

{
  "id": "b29a43a7-1949-4b9f-9d61-b7ae66f85d31",
  "name": "codex-chris-laptop",
  "delivery": {
    "type": "webhook",
    "url": "https://harness.example.com/aap/events",
    "registration_id": "8246931c-4ce0-4c15-a94a-e9c078ad06e2"
  }
}

Delete an instance

Retires an instance within the provisioner token's scope. Revokes all its credentials, cancels its pending requests and ends all webhook delivery. Existing terminal decisions stay unchanged. No cancellation notifications are sent for this operation. Attempts already in flight may still arrive. Deletion does not stop tool execution that has already begun.

The provider must serialize deletion with request creation, decisions and configuration updates so no pending work or active credential is left behind. Request and idempotency retention still apply. The provider keeps a deletion record for at least seven days; repeated deletion returns 204 whilst that record is retained. Unknown IDs return 404. No idempotency key is required. This operation never recreates an instance.

Parameters

Responses