---
title: "Register a devbox (idempotent POST)"
method: POST
path: "/orgs/{orgName}/devboxes/"
tags: ["Devboxes"]
---

# Register a devbox (idempotent POST)

`POST /orgs/{orgName}/devboxes/`

## Request

- Base URL: `https://api.signadot.com/api/v2`
- URL: `https://api.signadot.com/api/v2/orgs/{orgName}/devboxes/`
- Auth: none declared

Register a devbox with metadata. Returns 201 Created for new devbox, 200 OK if already exists. When authenticated via API key, creates org-scoped devboxes shared across all API keys in the org.

## Path parameters

- `orgName` string, required

## Request body

- DevboxRegistration
  - `claim` boolean
  - `metadata` object: Required: metadata key-value pairs. Only "name" and "machine-id" are used for ID generation.

## Response `200`

OK

- Devbox
  - `id` string: Deterministic ID derived from the owning principal + metadata ("name"/"machine-id").
  - `metadata` object: Only "name" and "machine-id" are used for ID generation.
  - `principal` DevboxPrincipal
    - `kind` string: Principal kind: "User" or "ServiceAccount".
    - `name` string: Display name: user email or service-account name.
    - `publicId` string: Principal public ID.
  - `status` DevboxStatus
    - `createdAt` string
    - `session` ConnectSession
      - `createdAt` string
      - `id` string
      - `renewedAt` string
      - `validUntil` string
    - `updatedAt` string
  - `user` string: DEPRECATED: owner email for User-owned devboxes, empty otherwise; use principal instead.

## Other responses

- `201`: Created
- `403`: Forbidden
- `429`: Too Many Requests
- `500`: Internal Server Error

## Changes

- **2025-12-05** `6969116f9791`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/signadot/apis/signadot-api/changes/orgs/:orgName/devboxes/post.md)

---

[API](https://skmtc.dev/signadot/apis/signadot-api.md) - [All operations](https://skmtc.dev/signadot/apis/signadot-api/llms.txt) - [OpenAPI document](https://skmtc.dev/signadot/apis/signadot-api/revisions/5e80b0f9c718?raw)