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

# Create your first organization

> Idempotent: answers with the caller's oldest organization when they already belong to one, and otherwise creates one named after them, with the caller as an admin. This is what signing up calls, so that onboarding never has to ask for a name. Refresh the AuthKit session into the organization to act inside it.



## OpenAPI

````yaml https://api.twinbay.ai/openapi.json post /organizations/default
openapi: 3.1.0
info:
  title: Twinbay
  description: Backend API
  version: 0.1.0
servers:
  - url: https://api.twinbay.ai
    description: Production
security: []
tags:
  - name: healthchecks
    description: Healthcheck endpoints
  - name: users
    description: >-
      The current user. Sign-up and sign-in happen in WorkOS AuthKit, which
      issues the access tokens this API accepts.
  - name: organizations
    description: >-
      Organizations the caller belongs to. Every authenticated request acts
      inside exactly one organization — the one its access token names — so
      these routes address it as `current`.
  - name: api-keys
    description: >-
      Long-lived credentials for callers that cannot hold an AuthKit session —
      agents, SDKs, CI. A key is accepted wherever an access token is, and acts
      with the role its creator holds when the request arrives.
  - name: sandboxes
    description: >-
      Create and edit isolated provider sandboxes. Each sandbox contains
      behavioural twins from the `twins` package.
  - name: twins
    description: Browse the digital twins available for new sandboxes.
paths:
  /organizations/default:
    post:
      tags:
        - organizations
      summary: Create your first organization
      description: >-
        Idempotent: answers with the caller's oldest organization when they
        already belong to one, and otherwise creates one named after them, with
        the caller as an admin. This is what signing up calls, so that
        onboarding never has to ask for a name. Refresh the AuthKit session into
        the organization to act inside it.
      operationId: ensure_default_organization
      responses:
        '200':
          description: The caller's organization and their role in it
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembershipResponse'
        '401':
          description: The credential is missing, malformed, expired, or not trusted
      security:
        - Access token: []
        - Organization API key: []
components:
  schemas:
    MembershipResponse:
      properties:
        organization:
          $ref: '#/components/schemas/OrganizationResponse'
        role:
          $ref: '#/components/schemas/OrganizationRole'
          description: The caller's role in this organization
      type: object
      required:
        - organization
        - role
      title: MembershipResponse
    OrganizationResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        workos_organization_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workos Organization Id
          description: >-
            WorkOS id of this organization. Clients need it to ask AuthKit for a
            token that acts here.
        name:
          type: string
          title: Name
        created_at:
          type: string
          format: date-time
          title: Created At
      type: object
      required:
        - id
        - workos_organization_id
        - name
        - created_at
      title: OrganizationResponse
    OrganizationRole:
      type: string
      enum:
        - admin
        - member
      title: OrganizationRole
  securitySchemes:
    Access token:
      type: http
      description: Access token issued by WorkOS AuthKit.
      scheme: bearer
    Organization API key:
      type: apiKey
      description: >-
        An organization API key, as minted by POST
        /organizations/current/api-keys.
      in: header
      name: X-API-Key

````