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

# Sign Up as an Agent

> Create an Orbit workspace for the person you work for and get an API key at once, with no sign-in.

An AI agent calls this endpoint to start using Orbit right away. No API key is
required. Orbit creates a workspace with the signup credits and returns an API
key for the agent. See [Let Your Agent Sign Up](https://docs.orbitsearch.com/agent-signup.md) for the full flow.

## Request

Send the email of the person you work for and a name they will recognize:

```json theme={"dark"}
{ "email": "jane@company.com", "agent_name": "Claude Code" }
```

The name appears in the workspace's member list.

## Response

`api_key` is returned only once. Store it in your private credential storage,
then send it as `Authorization: Bearer sk_orb_...` on Search, Enrich, and profile
reads. It has the `search:read` and `profile:read` scopes.

`sign_up_url` is Orbit's sign-up page. Give it to the person and ask them to sign
up with the same email. Orbit then adds them to the workspace as its owner, and
your key keeps working. Orbit does not contact the person itself.

## Errors

| Status | Code | What to do |
| - | - | - |
| `400` | `agent_signup_invalid_email` | Send the person's email address. |
| `400` | `agent_signup_email_not_allowed` | Use the person's real address, not a disposable or example domain. |
| `400` | `agent_signup_invalid_agent_name` | Send a short, readable `agent_name`. |
| `409` | `agent_signup_email_has_account` | The person already has an Orbit account. Ask them to sign in and connect you. |
| `409` | `agent_signup_already_exists` | An agent already created a workspace for this email. The person can sign up with this email to own it. |
| `503` | `agent_signup_unavailable` | Signup is paused or temporarily unavailable. Wait for `Retry-After`, or ask the person to sign in. |

Do not retry a `409` with another spelling of the same address. Each email gets
one signup.


## OpenAPI

````yaml openapi.json POST /v3/agents/signup
openapi: 3.1.0
info:
  title: Orbit API
  version: 3.0.0
  description: Search for people and enrich known Orbit profiles.
servers:
  - url: https://api.orbitsearch.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search
    description: Find people and poll search results.
  - name: Enrich
    description: Read or enrich known Orbit profiles.
  - name: People
    description: How people are connected.
  - name: Watchers
    description: Watch a profile on a schedule and read what each run found.
  - name: Webhooks
    description: Register endpoints that receive signed event deliveries.
  - name: Agents
    description: >-
      Let an AI agent create its own Orbit workspace, and hand it to the person
      it works for.
paths:
  /v3/agents/signup:
    post:
      tags:
        - Agents
      summary: Sign Up as an Agent
      description: >-
        Create an Orbit workspace for the person you work for and get an API key
        for it at once, with no sign-in. The workspace starts with the signup
        credit grant. The email is a referral: when the person signs up or signs
        in to Orbit with that verified email, they become the workspace's owner
        automatically, and your key keeps working. Orbit does not contact the
        person; give them `sign_up_url`. One signup per email address. An email
        that already has an Orbit account cannot be used: the person signs in
        and connects you instead. No API key is required.
      operationId: agentSignup
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - agent_name
              additionalProperties: false
              properties:
                email:
                  type: string
                  format: email
                  maxLength: 254
                  description: >-
                    The email address of the person you work for. Disposable and
                    example domains are refused.
                agent_name:
                  type: string
                  minLength: 1
                  maxLength: 80
                  description: >-
                    A name the person will recognize, such as `Claude Code`. It
                    appears in the workspace's member list.
            example:
              email: jane@company.com
              agent_name: Claude Code
      responses:
        '201':
          description: The workspace and key were created.
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - agent_signup
                properties:
                  status:
                    type: string
                    const: success
                  agent_signup:
                    $ref: '#/components/schemas/AgentSignup'
              example:
                status: success
                agent_signup:
                  id: 6f1c2a1e-1f7c-4a43-9b8e-2d3c9a0b5e11
                  status: unclaimed
                  organization_id: 0b6f7c55-3c1e-4c2b-8f4a-5d7e9a1b2c3d
                  email: jane@company.com
                  api_key: sk_orb_REDACTED
                  api_key_scopes:
                    - search:read
                    - profile:read
                  signup_credits: 200
                  sign_up_url: https://developer.orbitsearch.com/signup
        '400':
          description: >-
            The body is invalid: `agent_signup_invalid_body`,
            `agent_signup_invalid_email`, `agent_signup_email_not_allowed` (a
            disposable or example domain), or `agent_signup_invalid_agent_name`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: >-
            `agent_signup_email_has_account`: the email already has an Orbit
            account, so the person signs in and connects you instead.
            `agent_signup_already_exists`: an agent already created a workspace
            for this email; the person can sign up with this email to own it.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            `agent_signup_unavailable`: agent signup is paused or temporarily
            unavailable. Wait for `Retry-After`, or ask the person to sign in.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          headers:
            Retry-After:
              description: Seconds to wait before another request.
              schema:
                type: integer
                minimum: 0
      security: []
components:
  schemas:
    AgentSignup:
      type: object
      required:
        - id
        - status
        - organization_id
        - email
        - api_key
        - api_key_scopes
        - signup_credits
        - sign_up_url
      properties:
        id:
          type: string
          format: uuid
          description: The agent signup.
        status:
          type: string
          enum:
            - unclaimed
          description: '`unclaimed` until the person signs up or signs in with `email`.'
        organization_id:
          type: string
          format: uuid
          description: The workspace the agent and, later, the person share.
        email:
          type: string
          format: email
          description: >-
            The person's email, lowercased. Whoever signs up or signs in to
            Orbit with this verified email becomes the workspace's owner.
        api_key:
          type: string
          description: >-
            The agent's `sk_orb_...` key for the workspace. Returned only in
            this response; store it in the agent's private credential storage.
        api_key_scopes:
          type: array
          items:
            type: string
          description: Always `search:read` and `profile:read`.
        signup_credits:
          type: integer
          minimum: 0
          description: The free credits the workspace started with.
        sign_up_url:
          type: string
          format: uri
          description: >-
            Orbit's sign-up page. Give it to the person: signing up or signing
            in there with `email` makes them the workspace's owner. Orbit does
            not contact the person itself.
    ErrorResponse:
      type: object
      required:
        - status
        - error
      properties:
        status:
          type: string
          enum:
            - failed
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            requiredCredits:
              type: integer
              minimum: 0
              description: >-
                Credits required when the error is
                developer_api_credits_insufficient.
            remainingCredits:
              type: integer
              minimum: 0
              description: >-
                Available credits when the error is
                developer_api_credits_insufficient.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Orbit API key
      description: Use an Orbit API key from the Developer Dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.