Organizations API

Manage organizations and team members via the API.

Get Current Organization

GET /v1/organizations/current

Response:

{
  "data": {
    "id": "org_abc123",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "pro",
    "status": "active",
    "owner_id": "usr_xyz789",
    "settings": {
      "default_region": "us-east",
      "sso_enabled": false
    },
    "limits": {
      "members": 25,
      "projects": 10,
      "namespaces": 50
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}

List Organizations

GET /v1/organizations

Lists organizations the current user belongs to.

Response:

{
  "data": [
    {
      "id": "org_abc123",
      "name": "Acme Corp",
      "slug": "acme-corp",
      "plan": "pro",
      "role": "owner",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "org_def456",
      "name": "Side Project",
      "slug": "side-project",
      "plan": "starter",
      "role": "member",
      "created_at": "2024-02-01T08:00:00Z"
    }
  ]
}

Get Organization

GET /v1/organizations/:id

Response:

{
  "data": {
    "id": "org_abc123",
    "name": "Acme Corp",
    "slug": "acme-corp",
    "plan": "pro",
    "status": "active",
    "owner_id": "usr_xyz789",
    "member_count": 12,
    "settings": {
      "default_region": "us-east",
      "sso_enabled": false,
      "require_2fa": true
    },
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:00:00Z"
  }
}

Create Organization

POST /v1/organizations

Request Body:

{
  "name": "New Company",
  "slug": "new-company"
}

Response: 201 Created

{
  "data": {
    "id": "org_new123",
    "name": "New Company",
    "slug": "new-company",
    "plan": "free",
    "status": "active"
  }
}

Update Organization

PATCH /v1/organizations/:id

Request Body:

{
  "name": "Acme Corporation",
  "settings": {
    "default_region": "eu-west",
    "require_2fa": true
  }
}

Response:

{
  "data": {
    "id": "org_abc123",
    "name": "Acme Corporation",
    "settings": {
      "default_region": "eu-west",
      "require_2fa": true
    }
  }
}

Delete Organization

DELETE /v1/organizations/:id

Response: 204 No Content

Members

List Members

GET /v1/organizations/:id/members

Response:

{
  "data": [
    {
      "id": "mem_abc123",
      "user_id": "usr_xyz789",
      "email": "owner@acme.com",
      "name": "John Owner",
      "role": "owner",
      "joined_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "mem_def456",
      "user_id": "usr_abc789",
      "email": "dev@acme.com",
      "name": "Jane Developer",
      "role": "member",
      "joined_at": "2024-01-20T08:00:00Z"
    }
  ]
}

Invite Member

POST /v1/organizations/:id/members

Request Body:

{
  "email": "new-member@acme.com",
  "role": "member"
}

Response: 201 Created

{
  "data": {
    "id": "inv_abc123",
    "email": "new-member@acme.com",
    "role": "member",
    "status": "pending",
    "expires_at": "2024-01-22T10:30:00Z"
  }
}

Update Member Role

PATCH /v1/organizations/:id/members/:member_id

Request Body:

{
  "role": "admin"
}

Response:

{
  "data": {
    "id": "mem_def456",
    "role": "admin"
  }
}

Remove Member

DELETE /v1/organizations/:id/members/:member_id

Response: 204 No Content

Invitations

List Pending Invitations

GET /v1/organizations/:id/invitations

Response:

{
  "data": [
    {
      "id": "inv_abc123",
      "email": "pending@acme.com",
      "role": "member",
      "status": "pending",
      "invited_by": "usr_xyz789",
      "created_at": "2024-01-15T10:30:00Z",
      "expires_at": "2024-01-22T10:30:00Z"
    }
  ]
}

Resend Invitation

POST /v1/organizations/:id/invitations/:invitation_id/resend

Response:

{
  "data": {
    "id": "inv_abc123",
    "status": "pending",
    "expires_at": "2024-01-29T10:30:00Z"
  }
}

Revoke Invitation

DELETE /v1/organizations/:id/invitations/:invitation_id

Response: 204 No Content

Roles

Available roles:

Role	Description
owner	Full access, can delete organization
admin	Manage members and all resources
member	Create and manage own resources
viewer	Read-only access

API Keys

List Organization API Keys

GET /v1/organizations/:id/api-keys

Response:

{
  "data": [
    {
      "id": "key_abc123",
      "name": "CI/CD Pipeline",
      "prefix": "szc_prod_",
      "scopes": ["read:*", "write:namespaces"],
      "last_used_at": "2024-01-15T10:30:00Z",
      "expires_at": "2024-07-15T10:30:00Z",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Create API Key

POST /v1/organizations/:id/api-keys

Request Body:

{
  "name": "Deployment Key",
  "scopes": ["read:*", "write:namespaces", "write:registries"],
  "expires_in": "90d"
}

Response: 201 Created

{
  "data": {
    "id": "key_new123",
    "name": "Deployment Key",
    "key": "szc_prod_abc123xyz...",
    "prefix": "szc_prod_",
    "scopes": ["read:*", "write:namespaces", "write:registries"],
    "expires_at": "2024-04-15T10:30:00Z"
  }
}

The full API key is only shown once upon creation.

Revoke API Key

DELETE /v1/organizations/:id/api-keys/:key_id

Response: 204 No Content