Files
Nick Vigilante 7301cee2c4 fix: list every enum value the API can return in the Swagger spec (#30122)
The API reference is generated from Swagger comments and struct tags,
and several `enums:"..."` tags narrowed a named enum type, so the docs
omitted values the server returns. For example, `User.status` listed
only `active` and `suspended`, not `dormant`, and
`TemplateVersion.warnings` listed `DEPRECATED_PARAMETERS`, which is not
a value of the type.

Remove 34 `enums` tags that narrow or duplicate a named type so the
referenced type's full value list is used. Tags that describe an
intentional subset stay: ACL role fields (which omit the `""` deleted
sentinel used only in update requests), `APIKey.scope`, and plain-string
fields. `Template.provisioner` keeps its tag because `.swaggo` replaces
`ProvisionerType` with `string`.

Also fix enum defects that break code generators:

- The provisioner jobs and daemons `status` query parameters listed
their enum twice (Swagger 2.0 requires unique `enum` items) or with the
wrong type. Both are now `[]codersdk.ProvisionerJobStatus` and
`[]codersdk.ProvisionerDaemonStatus`, matching what each handler parses,
including comma-separated values. The daemons route previously
documented job statuses, which the handler rejects with a 500.
- Replace the `_` zero placeholder of `WatchErrorCode` with `iota + 1`,
so the spec no longer lists 0 or `x-enum-varnames: ["_", ...]`. Wire
values are unchanged.

Where the narrowed tag hid values the server returns, the SDK type now
includes them: `LoginTypeOAuth2ProviderApp`, `BuildReasonAutodelete`,
and `MissingTemplateParameter` widen the generated TypeScript unions.
The dashboard attributes `autodelete` builds to Coder like other system
builds. `APIKey.login_type` and `AuthorizationCheck.action` set explicit
examples so the generated samples stay representative.

`TestSwaggerEnumsNotNarrowed` fails when a property's enum list drops
values of its named type (other than the 15 allowlisted intentional
subsets), lists a value the type lacks, or repeats a value.

Part of DOCS-1122, split from #30121.

---
🤖 Built with AI assistance.
2026-11-10 17:42:30 -05:00

229 KiB
Generated

title
title
Enterprise

OAuth2 authorization server metadata

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/.well-known/oauth-authorization-server \
  -H 'Accept: application/json'

GET /.well-known/oauth-authorization-server

Example responses

200 Response

{
  "authorization_endpoint": "string",
  "code_challenge_methods_supported": [
    "S256"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "issuer": "string",
  "registration_endpoint": "string",
  "response_types_supported": [
    "code"
  ],
  "revocation_endpoint": "string",
  "scopes_supported": [
    "string"
  ],
  "token_endpoint": "string",
  "token_endpoint_auth_methods_supported": [
    "client_secret_basic"
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2AuthorizationServerMetadata

OAuth2 protected resource metadata

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/.well-known/oauth-protected-resource \
  -H 'Accept: application/json'

GET /.well-known/oauth-protected-resource

Example responses

200 Response

{
  "authorization_servers": [
    "string"
  ],
  "bearer_methods_supported": [
    "string"
  ],
  "resource": "string",
  "scopes_supported": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2ProtectedResourceMetadata

Get agent firewall session by ID

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/agent-firewall/sessions/{id} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/agent-firewall/sessions/{id}

Parameters

Name In Type Required Description
id path string(uuid) true Agent firewall session ID

Example responses

200 Response

{
  "confined_process": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  "started_at": "2019-08-24T14:15:22Z",
  "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.AgentFirewallSession

To perform this operation, you must be authenticated. Learn more.

Get agent firewall session logs

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/agent-firewall/sessions/{id}/logs \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/agent-firewall/sessions/{id}/logs

Parameters

Name In Type Required Description
id path string(uuid) true Agent firewall session ID
seq_after query integer false Inclusive lower bound on sequence number
seq_before query integer false Exclusive upper bound on sequence number
limit query integer false Maximum number of logs to return (default 100)

Example responses

200 Response

{
  "results": [
    {
      "allowed": true,
      "captured_at": "2019-08-24T14:15:22Z",
      "created_at": "2019-08-24T14:15:22Z",
      "detail": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "matched_rule": "string",
      "method": "string",
      "proto": "string",
      "sequence_number": 0,
      "session_id": "1ffd059c-17ea-40a8-8aef-70fd0307db82"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.AgentFirewallSessionLogsResponse

To perform this operation, you must be authenticated. Learn more.

List AI Gateway keys

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/ai-gateway/keys \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/ai-gateway/keys

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "key_prefix": "string",
    "last_heartbeat_at": "2019-08-24T14:15:22Z",
    "name": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.AIGatewayKey

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» created_at string(date-time) false
» id string(uuid) false
» key_prefix string false
» last_heartbeat_at string(date-time) false
» name string false

To perform this operation, you must be authenticated. Learn more.

Create AI Gateway key

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/ai-gateway/keys \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/ai-gateway/keys

Body parameter

{
  "name": "string"
}

Parameters

Name In Type Required Description
body body codersdk.CreateAIGatewayKeyRequest true Create AI Gateway key request

Example responses

201 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "key": "string",
  "key_prefix": "string",
  "name": "string"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.CreateAIGatewayKeyResponse

To perform this operation, you must be authenticated. Learn more.

Delete AI Gateway key

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/ai-gateway/keys/{key} \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/ai-gateway/keys/{key}

Parameters

Name In Type Required Description
key path string(uuid) true Key ID

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

AI Gateway serve

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/ai-gateway/serve \
  -H 'X-AI-Governance-Gateway-Key: API_KEY'

GET /api/v2/ai-gateway/serve

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

Get appearance

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/appearance \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/appearance

Example responses

200 Response

{
  "announcement_banners": [
    {
      "background_color": "string",
      "enabled": true,
      "message": "string"
    }
  ],
  "application_name": "string",
  "codernauts_enabled": true,
  "docs_url": "string",
  "logo_url": "string",
  "service_banner": {
    "background_color": "string",
    "enabled": true,
    "message": "string"
  },
  "support_links": [
    {
      "icon": "bug",
      "location": "navbar",
      "name": "string",
      "target": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.AppearanceConfig

To perform this operation, you must be authenticated. Learn more.

Update appearance

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/appearance \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/appearance

Body parameter

{
  "announcement_banners": [
    {
      "background_color": "string",
      "enabled": true,
      "message": "string"
    }
  ],
  "application_name": "string",
  "codernauts_enabled": true,
  "logo_url": "string",
  "service_banner": {
    "background_color": "string",
    "enabled": true,
    "message": "string"
  }
}

Parameters

Name In Type Required Description
body body codersdk.UpdateAppearanceConfig true Update appearance request

Example responses

200 Response

{
  "announcement_banners": [
    {
      "background_color": "string",
      "enabled": true,
      "message": "string"
    }
  ],
  "application_name": "string",
  "codernauts_enabled": true,
  "logo_url": "string",
  "service_banner": {
    "background_color": "string",
    "enabled": true,
    "message": "string"
  }
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UpdateAppearanceConfig

To perform this operation, you must be authenticated. Learn more.

Get connection logs

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/connectionlog?limit=0 \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/connectionlog

Parameters

Name In Type Required Description
q query string false Search query
limit query integer true Page limit
offset query integer false Page offset

Example responses

200 Response

{
  "connection_logs": [
    {
      "agent_name": "string",
      "app_display_name": "string",
      "app_name": "string",
      "connect_time": "2019-08-24T14:15:22Z",
      "connection_method": "ssh",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "ip": "string",
      "organization": {
        "display_name": "string",
        "icon": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "ssh_info": {
        "client_session_id": "string",
        "connection_id": "d3547de1-d1f2-4344-b4c2-17169b7526f9",
        "disconnect_reason": "string",
        "disconnect_time": "2019-08-24T14:15:22Z",
        "exit_code": 0
      },
      "type": "string",
      "web_info": {
        "slug_or_port": "string",
        "status_code": 0,
        "user": {
          "avatar_url": "http://example.com",
          "created_at": "2019-08-24T14:15:22Z",
          "email": "user@example.com",
          "has_ai_seat": true,
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "is_service_account": true,
          "last_seen_at": "2019-08-24T14:15:22Z",
          "login_type": "",
          "name": "string",
          "organization_ids": [
            "497f6eca-6276-4993-bfeb-53cbbbba6f08"
          ],
          "roles": [
            {
              "display_name": "string",
              "name": "string",
              "organization_id": "string"
            }
          ],
          "status": "active",
          "theme_preference": "string",
          "updated_at": "2019-08-24T14:15:22Z",
          "username": "string"
        },
        "user_agent": "string"
      },
      "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
      "workspace_name": "string",
      "workspace_owner_id": "e7078695-5279-4c86-8774-3ac2367a2fc7",
      "workspace_owner_username": "string"
    }
  ],
  "count": 0,
  "count_cap": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.ConnectionLogResponse

To perform this operation, you must be authenticated. Learn more.

Report a premium paywall click

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/deployment/premium-funnel-events \
  -H 'Content-Type: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/deployment/premium-funnel-events

Body parameter

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "source": "aibridge_session_threads",
  "variant": "premium"
}

Parameters

Name In Type Required Description
body body codersdk.PremiumFunnelEventRequest true Premium funnel event

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

Get entitlements

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/entitlements \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/entitlements

Example responses

200 Response

{
  "errors": [
    "string"
  ],
  "features": {
    "property1": {
      "actual": 0,
      "actual_ms": 0,
      "enabled": true,
      "entitlement": "entitled",
      "hard_limit": 0,
      "limit": 0,
      "soft_limit": 0,
      "usage_period": {
        "end": "2019-08-24T14:15:22Z",
        "issued_at": "2019-08-24T14:15:22Z",
        "start": "2019-08-24T14:15:22Z"
      }
    },
    "property2": {
      "actual": 0,
      "actual_ms": 0,
      "enabled": true,
      "entitlement": "entitled",
      "hard_limit": 0,
      "limit": 0,
      "soft_limit": 0,
      "usage_period": {
        "end": "2019-08-24T14:15:22Z",
        "issued_at": "2019-08-24T14:15:22Z",
        "start": "2019-08-24T14:15:22Z"
      }
    }
  },
  "has_license": true,
  "refreshed_at": "2019-08-24T14:15:22Z",
  "require_telemetry": true,
  "trial": true,
  "warnings": [
    "string"
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Entitlements

To perform this operation, you must be authenticated. Learn more.

Get groups

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/groups?organization=string&has_member=string&group_ids=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/groups

Parameters

Name In Type Required Description
organization query string true Organization ID or name
has_member query string true User ID or name
group_ids query string true Comma separated list of group IDs

Example responses

200 Response

[
  {
    "avatar_url": "http://example.com",
    "display_name": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "members": [
      {
        "avatar_url": "http://example.com",
        "created_at": "2019-08-24T14:15:22Z",
        "email": "user@example.com",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "is_service_account": true,
        "last_seen_at": "2019-08-24T14:15:22Z",
        "login_type": "",
        "name": "string",
        "status": "active",
        "theme_preference": "string",
        "updated_at": "2019-08-24T14:15:22Z",
        "username": "string"
      }
    ],
    "name": "string",
    "organization_display_name": "string",
    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "organization_name": "string",
    "quota_allowance": 0,
    "source": "user",
    "total_member_count": 0
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.Group

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» avatar_url string(uri) false
» display_name string false
» id string(uuid) false
» members array false
»» avatar_url string(uri) false
»» created_at string(date-time) true
»» email string(email) true
»» id string(uuid) true
»» is_service_account boolean false
»» last_seen_at string(date-time) false
»» login_type codersdk.LoginType false
»» name string false
»» status codersdk.UserStatus false
»» theme_preference string false Deprecated: this value should be retrieved from codersdk.UserPreferenceSettings instead.
»» updated_at string(date-time) false
»» username string true
» name string false
» organization_display_name string false
» organization_id string(uuid) false
» organization_name string false
» quota_allowance integer false
» source codersdk.GroupSource false
» total_member_count integer false How many members are in this group. Shows the total count, even if the user is not authorized to read group member details. May be greater than len(Group.Members).

Enumerated Values

Property Value(s)
login_type ``, github, none, oauth2_provider_app, oidc, password, token
status active, dormant, suspended
source oidc, user

To perform this operation, you must be authenticated. Learn more.

Get group by ID

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/groups/{group} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/groups/{group}

Parameters

Name In Type Required Description
group path string true Group id
exclude_members query boolean false Exclude members from the response

Example responses

200 Response

{
  "avatar_url": "http://example.com",
  "display_name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "members": [
    {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_service_account": true,
      "last_seen_at": "2019-08-24T14:15:22Z",
      "login_type": "",
      "name": "string",
      "status": "active",
      "theme_preference": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "username": "string"
    }
  ],
  "name": "string",
  "organization_display_name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "organization_name": "string",
  "quota_allowance": 0,
  "source": "user",
  "total_member_count": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Group

To perform this operation, you must be authenticated. Learn more.

Delete group by name

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/groups/{group} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/groups/{group}

Parameters

Name In Type Required Description
group path string true Group name

Example responses

200 Response

{
  "avatar_url": "http://example.com",
  "display_name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "members": [
    {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_service_account": true,
      "last_seen_at": "2019-08-24T14:15:22Z",
      "login_type": "",
      "name": "string",
      "status": "active",
      "theme_preference": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "username": "string"
    }
  ],
  "name": "string",
  "organization_display_name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "organization_name": "string",
  "quota_allowance": 0,
  "source": "user",
  "total_member_count": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Group

To perform this operation, you must be authenticated. Learn more.

Update group by name

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/groups/{group} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/groups/{group}

Body parameter

{
  "add_users": [
    "string"
  ],
  "avatar_url": "string",
  "display_name": "string",
  "name": "string",
  "quota_allowance": 0,
  "remove_users": [
    "string"
  ]
}

Parameters

Name In Type Required Description
group path string true Group name
body body codersdk.PatchGroupRequest true Patch group request

Example responses

200 Response

{
  "avatar_url": "http://example.com",
  "display_name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "members": [
    {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_service_account": true,
      "last_seen_at": "2019-08-24T14:15:22Z",
      "login_type": "",
      "name": "string",
      "status": "active",
      "theme_preference": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "username": "string"
    }
  ],
  "name": "string",
  "organization_display_name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "organization_name": "string",
  "quota_allowance": 0,
  "source": "user",
  "total_member_count": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Group

To perform this operation, you must be authenticated. Learn more.

Get group AI budget

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/groups/{group}/ai/budget \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/groups/{group}/ai/budget

Parameters

Name In Type Required Description
group path string(uuid) true Group ID

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "spend_limit_micros": 0,
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupAIBudget

To perform this operation, you must be authenticated. Learn more.

Upsert group AI budget

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/groups/{group}/ai/budget \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/groups/{group}/ai/budget

Body parameter

{
  "spend_limit_micros": 0
}

Parameters

Name In Type Required Description
group path string(uuid) true Group ID
body body codersdk.UpsertGroupAIBudgetRequest true Upsert group AI budget request

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "spend_limit_micros": 0,
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupAIBudget

To perform this operation, you must be authenticated. Learn more.

Delete group AI budget

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/groups/{group}/ai/budget \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/groups/{group}/ai/budget

Parameters

Name In Type Required Description
group path string(uuid) true Group ID

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

Get group AI spend

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/groups/{group}/ai/spend \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/groups/{group}/ai/spend

Returns the AI spend limit and aggregate spend for the group.

Parameters

Name In Type Required Description
group path string(uuid) true Group ID

Example responses

200 Response

{
  "current_spend_micros": 0,
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "period_end": "2019-08-24T14:15:22Z",
  "period_start": "2019-08-24T14:15:22Z",
  "spend_limit_micros": 0,
  "total_spend_limit_micros": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupAISpend

To perform this operation, you must be authenticated. Learn more.

Get group members by group ID

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/groups/{group}/members \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/groups/{group}/members

Parameters

Name In Type Required Description
group path string true Group id
q query string false Member search query
after_id query string(uuid) false After ID
limit query integer false Page limit
offset query integer false Page offset

Example responses

200 Response

{
  "count": 0,
  "users": [
    {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_service_account": true,
      "last_seen_at": "2019-08-24T14:15:22Z",
      "login_type": "",
      "name": "string",
      "status": "active",
      "theme_preference": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "username": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupMembersResponse

To perform this operation, you must be authenticated. Learn more.

Get group members AI spend

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/groups/{group}/members/ai/spend?user_ids=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/groups/{group}/members/ai/spend

Returns aggregate AI spend attributed to the group per requested user. A maximum of 100 user IDs may be requested per call, and requests with more are rejected, so callers are expected to batch across multiple requests. User IDs that are not members of the group, or that the caller has no read access to, are silently omitted.

Parameters

Name In Type Required Description
group path string(uuid) true Group ID
user_ids query string true Comma-separated list of user IDs (maximum 100)

Example responses

200 Response

{
  "members": [
    {
      "effective_budget": {
        "limit_source": "user_override",
        "spend_limit_micros": 0
      },
      "effective_group_id": "85e2b926-ddfb-4c66-b68e-b66e5acec6c0",
      "group_budget": {
        "limit_source": "user_override",
        "spend_limit_micros": 0
      },
      "group_spend_micros": 0,
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
    }
  ],
  "period_end": "2019-08-24T14:15:22Z",
  "period_start": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupMembersAISpend

To perform this operation, you must be authenticated. Learn more.

Get licenses

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/licenses \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/licenses

Example responses

200 Response

[
  {
    "claims": {},
    "id": 0,
    "uploaded_at": "2019-08-24T14:15:22Z",
    "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.License

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» claims object false Claims are the JWT claims asserted by the license. Here we use a generic string map to ensure that all data from the server is parsed verbatim, not just the fields this version of Coder understands.
» id integer false
» uploaded_at string(date-time) false
» uuid string(uuid) false

To perform this operation, you must be authenticated. Learn more.

Add new license

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/licenses \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/licenses

Body parameter

{
  "license": "string"
}

Parameters

Name In Type Required Description
body body codersdk.AddLicenseRequest true Add license request

Example responses

201 Response

{
  "claims": {},
  "id": 0,
  "uploaded_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.License

To perform this operation, you must be authenticated. Learn more.

Update license entitlements

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/licenses/refresh-entitlements \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/licenses/refresh-entitlements

Example responses

201 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Request a trial license

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/licenses/trial \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/licenses/trial

Body parameter

{
  "attribution_id": "6f882a62-1d45-46e1-b5f4-0abfea127010",
  "company_name": "Acme Corp",
  "country": "United States",
  "developers": "string",
  "email": "jane.doe@example.com",
  "first_name": "Jane",
  "job_title": "Engineering Manager",
  "last_name": "Doe",
  "phone_number": "+14155552671",
  "source": "aibridge_session_threads"
}

Parameters

Name In Type Required Description
body body codersdk.CreateTrialLicenseRequest true Trial license request

Example responses

201 Response

{
  "claims": {},
  "id": 0,
  "uploaded_at": "2019-08-24T14:15:22Z",
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.License

To perform this operation, you must be authenticated. Learn more.

Delete license

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/licenses/{id} \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/licenses/{id}

Parameters

Name In Type Required Description
id path string(number) true License ID

Responses

Status Meaning Description Schema
200 OK OK

To perform this operation, you must be authenticated. Learn more.

Update notification template dispatch method

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/notifications/templates/{notification_template}/method \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/notifications/templates/{notification_template}/method

Parameters

Name In Type Required Description
notification_template path string true Notification template UUID

Responses

Status Meaning Description Schema
200 OK Success
304 Not Modified Not modified

To perform this operation, you must be authenticated. Learn more.

Get OAuth2 applications

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/oauth2-provider/apps \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/oauth2-provider/apps

Parameters

Name In Type Required Description
user_id query string false Filter by applications authorized for a user

Example responses

200 Response

[
  {
    "callback_url": "string",
    "client_type": "confidential",
    "dynamically_registered": true,
    "endpoints": {
      "authorization": "string",
      "device_authorization": "string",
      "token": "string",
      "token_revoke": "string"
    },
    "icon": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "redirect_uris": [
      "string"
    ],
    "scope": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.OAuth2ProviderApp

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» callback_url string false Deprecated: equal to the first entry of redirect_uris. Read redirect_uris instead.
» client_type codersdk.OAuth2ClientType false Client type is "confidential" or "public".
» dynamically_registered boolean false Dynamically registered is true when the app registered itself through Dynamic Client Registration rather than being created by an admin.
» endpoints codersdk.OAuth2AppEndpoints false Endpoints are included in the app response for easier discovery. The OAuth2 spec does not have a defined place to find these (for comparison, OIDC has a '/.well-known/openid-configuration' endpoint).
»» authorization string false
»» device_authorization string false Device authorization is optional.
»» token string false
»» token_revoke string false
» icon string false
» id string(uuid) false
» name string false
» redirect_uris array false Redirect uris are the app's registered redirect URIs, primary first.
» scope string false Scope is the space-separated list of scopes this app's tokens may be granted. Empty means unrestricted. A non-empty value with no names is a configured allowlist that grants nothing.

Enumerated Values

Property Value(s)
client_type confidential, public

To perform this operation, you must be authenticated. Learn more.

Create OAuth2 application

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/oauth2-provider/apps \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/oauth2-provider/apps

Body parameter

{
  "callback_url": "string",
  "icon": "string",
  "name": "string",
  "redirect_uris": [
    "string"
  ],
  "scope": "string"
}

Parameters

Name In Type Required Description
body body codersdk.PostOAuth2ProviderAppRequest true The OAuth2 application to create.

Example responses

200 Response

{
  "callback_url": "string",
  "client_type": "confidential",
  "dynamically_registered": true,
  "endpoints": {
    "authorization": "string",
    "device_authorization": "string",
    "token": "string",
    "token_revoke": "string"
  },
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "redirect_uris": [
    "string"
  ],
  "scope": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2ProviderApp

To perform this operation, you must be authenticated. Learn more.

Get OAuth2 application

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/oauth2-provider/apps/{app} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/oauth2-provider/apps/{app}

Parameters

Name In Type Required Description
app path string true App ID

Example responses

200 Response

{
  "callback_url": "string",
  "client_type": "confidential",
  "dynamically_registered": true,
  "endpoints": {
    "authorization": "string",
    "device_authorization": "string",
    "token": "string",
    "token_revoke": "string"
  },
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "redirect_uris": [
    "string"
  ],
  "scope": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2ProviderApp

To perform this operation, you must be authenticated. Learn more.

Update OAuth2 application

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/oauth2-provider/apps/{app} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/oauth2-provider/apps/{app}

Body parameter

{
  "callback_url": "string",
  "icon": "string",
  "name": "string",
  "redirect_uris": [
    "string"
  ],
  "scope": "string"
}

Parameters

Name In Type Required Description
app path string true App ID
body body codersdk.PutOAuth2ProviderAppRequest true Update an OAuth2 application.

Example responses

200 Response

{
  "callback_url": "string",
  "client_type": "confidential",
  "dynamically_registered": true,
  "endpoints": {
    "authorization": "string",
    "device_authorization": "string",
    "token": "string",
    "token_revoke": "string"
  },
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "redirect_uris": [
    "string"
  ],
  "scope": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2ProviderApp

To perform this operation, you must be authenticated. Learn more.

Delete OAuth2 application

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/oauth2-provider/apps/{app} \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/oauth2-provider/apps/{app}

Parameters

Name In Type Required Description
app path string true App ID

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

Get OAuth2 application secrets

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/oauth2-provider/apps/{app}/secrets \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/oauth2-provider/apps/{app}/secrets

Parameters

Name In Type Required Description
app path string true App ID

Example responses

200 Response

[
  {
    "client_secret_truncated": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "last_used_at": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.OAuth2ProviderAppSecret

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» client_secret_truncated string false
» id string(uuid) false
» last_used_at string false

To perform this operation, you must be authenticated. Learn more.

Create OAuth2 application secret

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/oauth2-provider/apps/{app}/secrets \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/oauth2-provider/apps/{app}/secrets

Parameters

Name In Type Required Description
app path string true App ID

Example responses

200 Response

[
  {
    "client_secret_full": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.OAuth2ProviderAppSecretFull
400 Bad Request Public clients cannot have secrets codersdk.Response

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» client_secret_full string false
» id string(uuid) false

To perform this operation, you must be authenticated. Learn more.

Delete OAuth2 application secret

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/oauth2-provider/apps/{app}/secrets/{secretID} \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/oauth2-provider/apps/{app}/secrets/{secretID}

Parameters

Name In Type Required Description
app path string true App ID
secretID path string true Secret ID

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

Get OAuth2 provider settings

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/oauth2-provider/settings \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/oauth2-provider/settings

Example responses

200 Response

{
  "dynamic_client_registration_enabled": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2ProviderSettings

To perform this operation, you must be authenticated. Learn more.

Update OAuth2 provider settings

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/oauth2-provider/settings \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/oauth2-provider/settings

Body parameter

{
  "dynamic_client_registration_enabled": true
}

Parameters

Name In Type Required Description
body body codersdk.OAuth2ProviderSettings true OAuth2 provider settings request

Example responses

200 Response

{
  "dynamic_client_registration_enabled": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2ProviderSettings

To perform this operation, you must be authenticated. Learn more.

Export organization AI spend as CSV

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/ai/spend/export \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/ai/spend/export

Returns per-user, per-group, per-model, per-provider aggregated AI spend for the organization as CSV, built from raw AI Gateway token usage. The optional period_start and period_end query parameters bound the period and are interpreted as UTC. They must be provided together and span at most 31 days. When both are omitted, the current UTC monthly period is used. An explicit period_start must fall within the configured AI Gateway data retention window, since older token usage is purged. The default period is narrowed to that window instead, and every row echoes the applied bounds. Unknown query parameters are rejected. Requires organization-level administrator permissions.

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
period_start query string(date-time) false Inclusive lower bound (RFC3339)
period_end query string(date-time) false Exclusive upper bound (RFC3339)
user_id query string(uuid) false User ID
group_id query string(uuid) false Effective group ID
provider_name query string false Configured provider name
model query string false Model name

Responses

Status Meaning Description Schema
200 OK OK

To perform this operation, you must be authenticated. Learn more.

Get groups by organization

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/groups \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/groups

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID

Example responses

200 Response

[
  {
    "avatar_url": "http://example.com",
    "display_name": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "members": [
      {
        "avatar_url": "http://example.com",
        "created_at": "2019-08-24T14:15:22Z",
        "email": "user@example.com",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "is_service_account": true,
        "last_seen_at": "2019-08-24T14:15:22Z",
        "login_type": "",
        "name": "string",
        "status": "active",
        "theme_preference": "string",
        "updated_at": "2019-08-24T14:15:22Z",
        "username": "string"
      }
    ],
    "name": "string",
    "organization_display_name": "string",
    "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
    "organization_name": "string",
    "quota_allowance": 0,
    "source": "user",
    "total_member_count": 0
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.Group

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» avatar_url string(uri) false
» display_name string false
» id string(uuid) false
» members array false
»» avatar_url string(uri) false
»» created_at string(date-time) true
»» email string(email) true
»» id string(uuid) true
»» is_service_account boolean false
»» last_seen_at string(date-time) false
»» login_type codersdk.LoginType false
»» name string false
»» status codersdk.UserStatus false
»» theme_preference string false Deprecated: this value should be retrieved from codersdk.UserPreferenceSettings instead.
»» updated_at string(date-time) false
»» username string true
» name string false
» organization_display_name string false
» organization_id string(uuid) false
» organization_name string false
» quota_allowance integer false
» source codersdk.GroupSource false
» total_member_count integer false How many members are in this group. Shows the total count, even if the user is not authorized to read group member details. May be greater than len(Group.Members).

Enumerated Values

Property Value(s)
login_type ``, github, none, oauth2_provider_app, oidc, password, token
status active, dormant, suspended
source oidc, user

To perform this operation, you must be authenticated. Learn more.

Create group for organization

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/groups \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/organizations/{organization}/groups

Body parameter

{
  "avatar_url": "string",
  "display_name": "string",
  "name": "string",
  "quota_allowance": 0
}

Parameters

Name In Type Required Description
organization path string true Organization ID
body body codersdk.CreateGroupRequest true Create group request

Example responses

201 Response

{
  "avatar_url": "http://example.com",
  "display_name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "members": [
    {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_service_account": true,
      "last_seen_at": "2019-08-24T14:15:22Z",
      "login_type": "",
      "name": "string",
      "status": "active",
      "theme_preference": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "username": "string"
    }
  ],
  "name": "string",
  "organization_display_name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "organization_name": "string",
  "quota_allowance": 0,
  "source": "user",
  "total_member_count": 0
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.Group

To perform this operation, you must be authenticated. Learn more.

Get organization groups AI spend

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/groups/ai/spend?group_ids=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/groups/ai/spend

Returns AI spend limits and aggregate spend for the requested groups. A maximum of 100 group IDs may be requested per call, and requests with more are rejected, so callers are expected to batch across multiple requests. Unknown or unreadable group IDs are silently omitted.

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
group_ids query string true Comma-separated list of group IDs (maximum 100)

Example responses

200 Response

{
  "groups": [
    {
      "current_spend_micros": 0,
      "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
      "spend_limit_micros": 0,
      "total_spend_limit_micros": 0
    }
  ],
  "period_end": "2019-08-24T14:15:22Z",
  "period_start": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OrganizationGroupsAISpend

To perform this operation, you must be authenticated. Learn more.

Get group by organization and group name

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/groups/{groupName} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/groups/{groupName}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
groupName path string true Group name

Example responses

200 Response

{
  "avatar_url": "http://example.com",
  "display_name": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "members": [
    {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_service_account": true,
      "last_seen_at": "2019-08-24T14:15:22Z",
      "login_type": "",
      "name": "string",
      "status": "active",
      "theme_preference": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "username": "string"
    }
  ],
  "name": "string",
  "organization_display_name": "string",
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "organization_name": "string",
  "quota_allowance": 0,
  "source": "user",
  "total_member_count": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Group

To perform this operation, you must be authenticated. Learn more.

Get group members by organization and group name

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/groups/{groupName}/members \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/groups/{groupName}/members

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
groupName path string true Group name
q query string false Member search query
after_id query string(uuid) false After ID
limit query integer false Page limit
offset query integer false Page offset

Example responses

200 Response

{
  "count": 0,
  "users": [
    {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_service_account": true,
      "last_seen_at": "2019-08-24T14:15:22Z",
      "login_type": "",
      "name": "string",
      "status": "active",
      "theme_preference": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "username": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupMembersResponse

To perform this operation, you must be authenticated. Learn more.

Get group members AI spend by organization

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/groups/{groupName}/members/ai/spend?user_ids=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/groups/{groupName}/members/ai/spend

Returns aggregate AI spend attributed to the group per requested user. A maximum of 100 user IDs may be requested per call, and requests with more are rejected, so callers are expected to batch across multiple requests. User IDs that are not members of the group, or that the caller has no read access to, are silently omitted.

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
groupName path string true Group name
user_ids query string true Comma-separated list of user IDs (maximum 100)

Example responses

200 Response

{
  "members": [
    {
      "effective_budget": {
        "limit_source": "user_override",
        "spend_limit_micros": 0
      },
      "effective_group_id": "85e2b926-ddfb-4c66-b68e-b66e5acec6c0",
      "group_budget": {
        "limit_source": "user_override",
        "spend_limit_micros": 0
      },
      "group_spend_micros": 0,
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
    }
  ],
  "period_end": "2019-08-24T14:15:22Z",
  "period_start": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupMembersAISpend

To perform this operation, you must be authenticated. Learn more.

Get workspace quota by user

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/members/{user}/workspace-quota \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/members/{user}/workspace-quota

Parameters

Name In Type Required Description
user path string true User ID, name, or me
organization path string(uuid) true Organization ID

Example responses

200 Response

{
  "budget": 0,
  "credits_consumed": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceQuota

To perform this operation, you must be authenticated. Learn more.

Get groups by organization (paginated)

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/paginated-groups \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/paginated-groups

Unlike "Get groups by organization" (GET /organizations/{organization}/groups), which authorizes each group individually via its ACL, this endpoint requires organization-wide group read permission and does no per-group filtering. It is therefore not a drop-in replacement: callers without org-wide group read receive an error rather than a filtered subset.

The q parameter uses the shared filter syntax. Bare terms (including multi-word) perform a free-text search over group name and display name. search: is the only accepted key and unknown keys return 400. Because group display names may contain colons, a value with a colon must be quoted, e.g. search:"team: frontend"; an unquoted colon fails with Query element "team:" cannot start or end with ':'.

This endpoint returns group summaries without the member roster: each group carries only total_member_count and no members field. Callers that need the roster use the group members endpoint (GET /groups/{group}/members).

Parameters

Name In Type Required Description
organization path string true Organization ID or name
q query string false Search query (see description for syntax and colon-quoting)
limit query integer false Page limit
offset query integer false Page offset
after_id query string(uuid) false After ID

Example responses

200 Response

{
  "count": 0,
  "groups": [
    {
      "avatar_url": "http://example.com",
      "display_name": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "organization_display_name": "string",
      "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
      "organization_name": "string",
      "quota_allowance": 0,
      "source": "user",
      "total_member_count": 0
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.PaginatedGroupsResponse

To perform this operation, you must be authenticated. Learn more.

Serve provisioner daemon

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerdaemons/serve \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/provisionerdaemons/serve

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID

Responses

Status Meaning Description Schema
101 Switching Protocols Switching Protocols

To perform this operation, you must be authenticated. Learn more.

List provisioner key

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerkeys \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/provisionerkeys

Parameters

Name In Type Required Description
organization path string true Organization ID

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "string",
    "organization": "452c1a86-a0af-475b-b03f-724878b0f387",
    "tags": {
      "property1": "string",
      "property2": "string"
    }
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.ProvisionerKey

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» created_at string(date-time) false
» id string(uuid) false
» name string false
» organization string(uuid) false
» tags codersdk.ProvisionerKeyTags false
»» [any property] string false

To perform this operation, you must be authenticated. Learn more.

Create provisioner key

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/organizations/{organization}/provisionerkeys \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/organizations/{organization}/provisionerkeys

Parameters

Name In Type Required Description
organization path string true Organization ID

Example responses

201 Response

{
  "key": "string"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.CreateProvisionerKeyResponse

To perform this operation, you must be authenticated. Learn more.

List provisioner key daemons

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/provisionerkeys/daemons \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/provisionerkeys/daemons

Parameters

Name In Type Required Description
organization path string true Organization ID

Example responses

200 Response

[
  {
    "daemons": [
      {
        "api_version": "string",
        "created_at": "2019-08-24T14:15:22Z",
        "current_job": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "status": "pending",
          "template_display_name": "string",
          "template_icon": "string",
          "template_name": "string"
        },
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "key_id": "1e779c8a-6786-4c89-b7c3-a6666f5fd6b5",
        "key_name": "string",
        "last_seen_at": "2019-08-24T14:15:22Z",
        "name": "string",
        "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
        "previous_job": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "status": "pending",
          "template_display_name": "string",
          "template_icon": "string",
          "template_name": "string"
        },
        "provisioners": [
          "string"
        ],
        "status": "offline",
        "tags": {
          "property1": "string",
          "property2": "string"
        },
        "version": "string"
      }
    ],
    "key": {
      "created_at": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "string",
      "organization": "452c1a86-a0af-475b-b03f-724878b0f387",
      "tags": {
        "property1": "string",
        "property2": "string"
      }
    }
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.ProvisionerKeyDaemons

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» daemons array false
»» api_version string false
»» created_at string(date-time) false
»» current_job codersdk.ProvisionerDaemonJob false
»»» id string(uuid) false
»»» status codersdk.ProvisionerJobStatus false
»»» template_display_name string false
»»» template_icon string false
»»» template_name string false
»» id string(uuid) false
»» key_id string(uuid) false
»» key_name string false Optional fields.
»» last_seen_at string(date-time) false
»» name string false
»» organization_id string(uuid) false
»» previous_job codersdk.ProvisionerDaemonJob false
»» provisioners array false
»» status codersdk.ProvisionerDaemonStatus false
»» tags object false
»»» [any property] string false
»» version string false
» key codersdk.ProvisionerKey false
»» created_at string(date-time) false
»» id string(uuid) false
»» name string false
»» organization string(uuid) false
»» tags codersdk.ProvisionerKeyTags false
»»» [any property] string false

Enumerated Values

Property Value(s)
status busy, canceled, canceling, failed, idle, offline, pending, running, succeeded, unknown

To perform this operation, you must be authenticated. Learn more.

Delete provisioner key

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/organizations/{organization}/provisionerkeys/{provisionerkey} \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/organizations/{organization}/provisionerkeys/{provisionerkey}

Parameters

Name In Type Required Description
organization path string true Organization ID
provisionerkey path string true Provisioner key name

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

Get the available organization idp sync claim fields

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/available-fields \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/settings/idpsync/available-fields

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID

Example responses

200 Response

[
  "string"
]

Responses

Status Meaning Description Schema
200 OK OK array of string

Response Schema

To perform this operation, you must be authenticated. Learn more.

Get the organization idp sync claim field values

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/field-values?claimField=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/settings/idpsync/field-values

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
claimField query string(string) true Claim Field

Example responses

200 Response

[
  "string"
]

Responses

Status Meaning Description Schema
200 OK OK array of string

Response Schema

To perform this operation, you must be authenticated. Learn more.

Get group IdP Sync settings by organization

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/groups \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/settings/idpsync/groups

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID

Example responses

200 Response

{
  "auto_create_missing_groups": true,
  "field": "string",
  "legacy_group_name_mapping": {
    "property1": "string",
    "property2": "string"
  },
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "regex_filter": {}
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update group IdP Sync settings by organization

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/groups \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/organizations/{organization}/settings/idpsync/groups

Body parameter

{
  "auto_create_missing_groups": true,
  "field": "string",
  "legacy_group_name_mapping": {
    "property1": "string",
    "property2": "string"
  },
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "regex_filter": {}
}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
body body codersdk.GroupSyncSettings true New settings

Example responses

200 Response

{
  "auto_create_missing_groups": true,
  "field": "string",
  "legacy_group_name_mapping": {
    "property1": "string",
    "property2": "string"
  },
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "regex_filter": {}
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update group IdP Sync config

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/groups/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/organizations/{organization}/settings/idpsync/groups/config

Body parameter

{
  "auto_create_missing_groups": true,
  "field": "string",
  "regex_filter": {}
}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID or name
body body codersdk.PatchGroupIDPSyncConfigRequest true New config values

Example responses

200 Response

{
  "auto_create_missing_groups": true,
  "field": "string",
  "legacy_group_name_mapping": {
    "property1": "string",
    "property2": "string"
  },
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "regex_filter": {}
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update group IdP Sync mapping

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/groups/mapping \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/organizations/{organization}/settings/idpsync/groups/mapping

Body parameter

{
  "add": [
    {
      "gets": "string",
      "given": "string"
    }
  ],
  "remove": [
    {
      "gets": "string",
      "given": "string"
    }
  ]
}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID or name
body body codersdk.PatchGroupIDPSyncMappingRequest true Description of the mappings to add and remove

Example responses

200 Response

{
  "auto_create_missing_groups": true,
  "field": "string",
  "legacy_group_name_mapping": {
    "property1": "string",
    "property2": "string"
  },
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "regex_filter": {}
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GroupSyncSettings

To perform this operation, you must be authenticated. Learn more.

Get role IdP Sync settings by organization

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/roles \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/settings/idpsync/roles

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID

Example responses

200 Response

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.RoleSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update role IdP Sync settings by organization

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/roles \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/organizations/{organization}/settings/idpsync/roles

Body parameter

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
body body codersdk.RoleSyncSettings true New settings

Example responses

200 Response

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.RoleSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update role IdP Sync config

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/roles/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/organizations/{organization}/settings/idpsync/roles/config

Body parameter

{
  "field": "string"
}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID or name
body body codersdk.PatchRoleIDPSyncConfigRequest true New config values

Example responses

200 Response

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.RoleSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update role IdP Sync mapping

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization}/settings/idpsync/roles/mapping \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/organizations/{organization}/settings/idpsync/roles/mapping

Body parameter

{
  "add": [
    {
      "gets": "string",
      "given": "string"
    }
  ],
  "remove": [
    {
      "gets": "string",
      "given": "string"
    }
  ]
}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID or name
body body codersdk.PatchRoleIDPSyncMappingRequest true Description of the mappings to add and remove

Example responses

200 Response

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  }
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.RoleSyncSettings

To perform this operation, you must be authenticated. Learn more.

Get workspace sharing settings for organization

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/organizations/{organization}/settings/workspace-sharing \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/organizations/{organization}/settings/workspace-sharing

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID

Example responses

200 Response

{
  "shareable_workspace_owners": "none",
  "sharing_disabled": true,
  "sharing_globally_disabled": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceSharingSettings

To perform this operation, you must be authenticated. Learn more.

Update workspace sharing settings for organization

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/organizations/{organization}/settings/workspace-sharing \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/organizations/{organization}/settings/workspace-sharing

Body parameter

{
  "shareable_workspace_owners": "none",
  "sharing_disabled": true
}

Parameters

Name In Type Required Description
organization path string(uuid) true Organization ID
body body codersdk.UpdateWorkspaceSharingSettingsRequest true Workspace sharing settings

Example responses

200 Response

{
  "shareable_workspace_owners": "none",
  "sharing_disabled": true,
  "sharing_globally_disabled": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceSharingSettings

To perform this operation, you must be authenticated. Learn more.

Fetch provisioner key details

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/provisionerkeys/{provisionerkey} \
  -H 'Accept: application/json'

GET /api/v2/provisionerkeys/{provisionerkey}

Parameters

Name In Type Required Description
provisionerkey path string true Provisioner Key

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "organization": "452c1a86-a0af-475b-b03f-724878b0f387",
  "tags": {
    "property1": "string",
    "property2": "string"
  }
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.ProvisionerKey

To perform this operation, you must be authenticated. Learn more.

Get active replicas

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/replicas \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/replicas

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "database_latency": 0,
    "error": "string",
    "hostname": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "region_id": 0,
    "relay_address": "string"
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.Replica

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» created_at string(date-time) false Created at is the timestamp when the replica was first seen.
» database_latency integer false Database latency is the latency in microseconds to the database.
» error string false Error is the replica error.
» hostname string false Hostname is the hostname of the replica.
» id string(uuid) false ID is the unique identifier for the replica.
» region_id integer false Region ID is the region of the replica.
» relay_address string false Relay address is the accessible address to relay DERP connections.

To perform this operation, you must be authenticated. Learn more.

Get the available idp sync claim fields

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/settings/idpsync/available-fields \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/settings/idpsync/available-fields

Example responses

200 Response

[
  "string"
]

Responses

Status Meaning Description Schema
200 OK OK array of string

Response Schema

To perform this operation, you must be authenticated. Learn more.

Get the idp sync claim field values

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/settings/idpsync/field-values?claimField=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/settings/idpsync/field-values

Parameters

Name In Type Required Description
claimField query string(string) true Claim Field

Example responses

200 Response

[
  "string"
]

Responses

Status Meaning Description Schema
200 OK OK array of string

Response Schema

To perform this operation, you must be authenticated. Learn more.

Get organization IdP Sync settings

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/settings/idpsync/organization \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/settings/idpsync/organization

Example responses

200 Response

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "organization_assign_default": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OrganizationSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update organization IdP Sync settings

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/settings/idpsync/organization \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/settings/idpsync/organization

Body parameter

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "organization_assign_default": true
}

Parameters

Name In Type Required Description
body body codersdk.OrganizationSyncSettings true New settings

Example responses

200 Response

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "organization_assign_default": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OrganizationSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update organization IdP Sync config

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/settings/idpsync/organization/config \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/settings/idpsync/organization/config

Body parameter

{
  "assign_default": true,
  "field": "string"
}

Parameters

Name In Type Required Description
body body codersdk.PatchOrganizationIDPSyncConfigRequest true New config values

Example responses

200 Response

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "organization_assign_default": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OrganizationSyncSettings

To perform this operation, you must be authenticated. Learn more.

Update organization IdP Sync mapping

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/settings/idpsync/organization/mapping \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/settings/idpsync/organization/mapping

Body parameter

{
  "add": [
    {
      "gets": "string",
      "given": "string"
    }
  ],
  "remove": [
    {
      "gets": "string",
      "given": "string"
    }
  ]
}

Parameters

Name In Type Required Description
body body codersdk.PatchOrganizationIDPSyncMappingRequest true Description of the mappings to add and remove

Example responses

200 Response

{
  "field": "string",
  "mapping": {
    "property1": [
      "string"
    ],
    "property2": [
      "string"
    ]
  },
  "organization_assign_default": true
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OrganizationSyncSettings

To perform this operation, you must be authenticated. Learn more.

Get template ACLs

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates/{template}/acl \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/templates/{template}/acl

Parameters

Name In Type Required Description
template path string(uuid) true Template ID

Example responses

200 Response

{
  "group": [
    {
      "avatar_url": "http://example.com",
      "display_name": "string",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "members": [
        {
          "avatar_url": "http://example.com",
          "created_at": "2019-08-24T14:15:22Z",
          "email": "user@example.com",
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "is_service_account": true,
          "last_seen_at": "2019-08-24T14:15:22Z",
          "login_type": "",
          "name": "string",
          "status": "active",
          "theme_preference": "string",
          "updated_at": "2019-08-24T14:15:22Z",
          "username": "string"
        }
      ],
      "name": "string",
      "organization_display_name": "string",
      "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
      "organization_name": "string",
      "quota_allowance": 0,
      "role": "admin",
      "source": "user",
      "total_member_count": 0
    }
  ],
  "users": [
    {
      "avatar_url": "http://example.com",
      "created_at": "2019-08-24T14:15:22Z",
      "email": "user@example.com",
      "has_ai_seat": true,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "is_service_account": true,
      "last_seen_at": "2019-08-24T14:15:22Z",
      "login_type": "",
      "name": "string",
      "organization_ids": [
        "497f6eca-6276-4993-bfeb-53cbbbba6f08"
      ],
      "role": "admin",
      "roles": [
        {
          "display_name": "string",
          "name": "string",
          "organization_id": "string"
        }
      ],
      "status": "active",
      "theme_preference": "string",
      "updated_at": "2019-08-24T14:15:22Z",
      "username": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.TemplateACL

To perform this operation, you must be authenticated. Learn more.

Update template ACL

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/templates/{template}/acl \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/templates/{template}/acl

Body parameter

{
  "group_perms": {
    "8bd26b20-f3e8-48be-a903-46bb920cf671": "use",
    "<group_id>": "admin"
  },
  "user_perms": {
    "4df59e74-c027-470b-ab4d-cbba8963a5e9": "use",
    "<user_id>": "admin"
  }
}

Parameters

Name In Type Required Description
template path string(uuid) true Template ID
body body codersdk.UpdateTemplateACL true Update template ACL request

Example responses

200 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Get template available acl users/groups

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/templates/{template}/acl/available \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/templates/{template}/acl/available

Parameters

Name In Type Required Description
template path string(uuid) true Template ID

Example responses

200 Response

[
  {
    "groups": [
      {
        "avatar_url": "http://example.com",
        "display_name": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "members": [
          {
            "avatar_url": "http://example.com",
            "created_at": "2019-08-24T14:15:22Z",
            "email": "user@example.com",
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "is_service_account": true,
            "last_seen_at": "2019-08-24T14:15:22Z",
            "login_type": "",
            "name": "string",
            "status": "active",
            "theme_preference": "string",
            "updated_at": "2019-08-24T14:15:22Z",
            "username": "string"
          }
        ],
        "name": "string",
        "organization_display_name": "string",
        "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
        "organization_name": "string",
        "quota_allowance": 0,
        "source": "user",
        "total_member_count": 0
      }
    ],
    "users": [
      {
        "avatar_url": "http://example.com",
        "created_at": "2019-08-24T14:15:22Z",
        "email": "user@example.com",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "is_service_account": true,
        "last_seen_at": "2019-08-24T14:15:22Z",
        "login_type": "",
        "name": "string",
        "status": "active",
        "theme_preference": "string",
        "updated_at": "2019-08-24T14:15:22Z",
        "username": "string"
      }
    ]
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.ACLAvailable

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» groups array false
»» avatar_url string(uri) false
»» display_name string false
»» id string(uuid) false
»» members array false
»»» avatar_url string(uri) false
»»» created_at string(date-time) true
»»» email string(email) true
»»» id string(uuid) true
»»» is_service_account boolean false
»»» last_seen_at string(date-time) false
»»» login_type codersdk.LoginType false
»»» name string false
»»» status codersdk.UserStatus false
»»» theme_preference string false Deprecated: this value should be retrieved from codersdk.UserPreferenceSettings instead.
»»» updated_at string(date-time) false
»»» username string true
»» name string false
»» organization_display_name string false
»» organization_id string(uuid) false
»» organization_name string false
»» quota_allowance integer false
»» source codersdk.GroupSource false
»» total_member_count integer false How many members are in this group. Shows the total count, even if the user is not authorized to read group member details. May be greater than len(Group.Members).
» users array false

Enumerated Values

Property Value(s)
login_type ``, github, none, oauth2_provider_app, oidc, password, token
status active, dormant, suspended
source oidc, user

To perform this operation, you must be authenticated. Learn more.

Invalidate presets for template

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/templates/{template}/prebuilds/invalidate \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/templates/{template}/prebuilds/invalidate

Parameters

Name In Type Required Description
template path string(uuid) true Template ID

Example responses

200 Response

{
  "invalidated": [
    {
      "preset_name": "string",
      "template_name": "string",
      "template_version_name": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.InvalidatePresetsResponse

To perform this operation, you must be authenticated. Learn more.

Get user AI budget override

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/{user}/ai/budget/override \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/users/{user}/ai/budget/override

Parameters

Name In Type Required Description
user path string true User ID, username, or me

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "spend_limit_micros": 0,
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UserAIBudgetOverride

To perform this operation, you must be authenticated. Learn more.

Upsert user AI budget override

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/users/{user}/ai/budget/override \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/users/{user}/ai/budget/override

Body parameter

{
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "spend_limit_micros": 0
}

Parameters

Name In Type Required Description
user path string true User ID, username, or me
body body codersdk.UpsertUserAIBudgetOverrideRequest true Upsert user AI budget override request

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
  "spend_limit_micros": 0,
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UserAIBudgetOverride

To perform this operation, you must be authenticated. Learn more.

Delete user AI budget override

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/users/{user}/ai/budget/override \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/users/{user}/ai/budget/override

Parameters

Name In Type Required Description
user path string true User ID, username, or me

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

Get user AI spend

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/{user}/ai/spend \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/users/{user}/ai/spend

Parameters

Name In Type Required Description
user path string true User ID, username, or me

Example responses

200 Response

{
  "current_spend_micros": 0,
  "effective_budget": {
    "limit_source": "user_override",
    "spend_limit_micros": 0
  },
  "effective_group_id": "85e2b926-ddfb-4c66-b68e-b66e5acec6c0",
  "period_end": "2019-08-24T14:15:22Z",
  "period_start": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UserAISpendStatus

To perform this operation, you must be authenticated. Learn more.

Get user quiet hours schedule

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/{user}/quiet-hours \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/users/{user}/quiet-hours

Parameters

Name In Type Required Description
user path string(uuid) true User ID

Example responses

200 Response

[
  {
    "next": "2019-08-24T14:15:22Z",
    "raw_schedule": "string",
    "time": "string",
    "timezone": "string",
    "user_can_set": true,
    "user_set": true
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.UserQuietHoursScheduleResponse

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» next string(date-time) false Next is the next time that the quiet hours window will start.
» raw_schedule string false
» time string false Time is the time of day that the quiet hours window starts in the given Timezone each day.
» timezone string false raw format from the cron expression, UTC if unspecified
» user_can_set boolean false User can set is true if the user is allowed to set their own quiet hours schedule. If false, the user cannot set a custom schedule and the default schedule will always be used.
» user_set boolean false User set is true if the user has set their own quiet hours schedule. If false, the user is using the default schedule.

To perform this operation, you must be authenticated. Learn more.

Update user quiet hours schedule

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/users/{user}/quiet-hours \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/users/{user}/quiet-hours

Body parameter

{
  "schedule": "string"
}

Parameters

Name In Type Required Description
user path string(uuid) true User ID
body body codersdk.UpdateUserQuietHoursScheduleRequest true Update schedule request

Example responses

200 Response

[
  {
    "next": "2019-08-24T14:15:22Z",
    "raw_schedule": "string",
    "time": "string",
    "timezone": "string",
    "user_can_set": true,
    "user_set": true
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.UserQuietHoursScheduleResponse

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» next string(date-time) false Next is the next time that the quiet hours window will start.
» raw_schedule string false
» time string false Time is the time of day that the quiet hours window starts in the given Timezone each day.
» timezone string false raw format from the cron expression, UTC if unspecified
» user_can_set boolean false User can set is true if the user is allowed to set their own quiet hours schedule. If false, the user cannot set a custom schedule and the default schedule will always be used.
» user_set boolean false User set is true if the user has set their own quiet hours schedule. If false, the user is using the default schedule.

To perform this operation, you must be authenticated. Learn more.

Get workspace quota by user deprecated

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspace-quota/{user} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/workspace-quota/{user}

Parameters

Name In Type Required Description
user path string true User ID, name, or me

Example responses

200 Response

{
  "budget": 0,
  "credits_consumed": 0
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceQuota

To perform this operation, you must be authenticated. Learn more.

Get workspace proxies

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceproxies \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/workspaceproxies

Example responses

200 Response

[
  {
    "regions": [
      {
        "created_at": "2019-08-24T14:15:22Z",
        "deleted": true,
        "derp_enabled": true,
        "derp_only": true,
        "display_name": "string",
        "healthy": true,
        "icon_url": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string",
        "path_app_url": "string",
        "status": {
          "checked_at": "2019-08-24T14:15:22Z",
          "report": {
            "errors": [
              "string"
            ],
            "warnings": [
              "string"
            ]
          },
          "status": "ok"
        },
        "updated_at": "2019-08-24T14:15:22Z",
        "version": "string",
        "wildcard_hostname": "string"
      }
    ]
  }
]

Responses

Status Meaning Description Schema
200 OK OK array of codersdk.RegionsResponse-codersdk_WorkspaceProxy

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» regions array false
»» created_at string(date-time) false
»» deleted boolean false
»» derp_enabled boolean false
»» derp_only boolean false
»» display_name string false
»» healthy boolean false
»» icon_url string false
»» id string(uuid) false
»» name string false
»» path_app_url string false Path app URL is the URL to the base path for path apps. Optional unless wildcard_hostname is set. E.g. https://us.example.com
»» status codersdk.WorkspaceProxyStatus false Status is the latest status check of the proxy. This will be empty for deleted proxies. This value can be used to determine if a workspace proxy is healthy and ready to use.
»»» checked_at string(date-time) false
»»» report codersdk.ProxyHealthReport false Report provides more information about the health of the workspace proxy.
»»»» errors array false Errors are problems that prevent the workspace proxy from being healthy
»»»» warnings array false Warnings do not prevent the workspace proxy from being healthy, but should be addressed.
»»» status codersdk.ProxyHealthStatus false
»» updated_at string(date-time) false
»» version string false
»» wildcard_hostname string false Wildcard hostname is the wildcard hostname for subdomain apps. E.g. .us.example.com E.g.--suffix.au.example.com Optional. Does not need to be on the same domain as PathAppURL.

Enumerated Values

Property Value(s)
status ok, unhealthy, unreachable, unregistered

To perform this operation, you must be authenticated. Learn more.

Create workspace proxy

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/workspaceproxies \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /api/v2/workspaceproxies

Body parameter

{
  "display_name": "string",
  "icon": "string",
  "name": "string"
}

Parameters

Name In Type Required Description
body body codersdk.CreateWorkspaceProxyRequest true Create workspace proxy request

Example responses

201 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "deleted": true,
  "derp_enabled": true,
  "derp_only": true,
  "display_name": "string",
  "healthy": true,
  "icon_url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "path_app_url": "string",
  "status": {
    "checked_at": "2019-08-24T14:15:22Z",
    "report": {
      "errors": [
        "string"
      ],
      "warnings": [
        "string"
      ]
    },
    "status": "ok"
  },
  "updated_at": "2019-08-24T14:15:22Z",
  "version": "string",
  "wildcard_hostname": "string"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.WorkspaceProxy

To perform this operation, you must be authenticated. Learn more.

Get workspace proxy

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaceproxies/{workspaceproxy} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/workspaceproxies/{workspaceproxy}

Parameters

Name In Type Required Description
workspaceproxy path string(uuid) true Proxy ID or name

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "deleted": true,
  "derp_enabled": true,
  "derp_only": true,
  "display_name": "string",
  "healthy": true,
  "icon_url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "path_app_url": "string",
  "status": {
    "checked_at": "2019-08-24T14:15:22Z",
    "report": {
      "errors": [
        "string"
      ],
      "warnings": [
        "string"
      ]
    },
    "status": "ok"
  },
  "updated_at": "2019-08-24T14:15:22Z",
  "version": "string",
  "wildcard_hostname": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceProxy

To perform this operation, you must be authenticated. Learn more.

Delete workspace proxy

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/api/v2/workspaceproxies/{workspaceproxy} \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

DELETE /api/v2/workspaceproxies/{workspaceproxy}

Parameters

Name In Type Required Description
workspaceproxy path string(uuid) true Proxy ID or name

Example responses

200 Response

{
  "detail": "string",
  "message": "string",
  "validations": [
    {
      "detail": "string",
      "field": "string"
    }
  ]
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Response

To perform this operation, you must be authenticated. Learn more.

Update workspace proxy

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/api/v2/workspaceproxies/{workspaceproxy} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

PATCH /api/v2/workspaceproxies/{workspaceproxy}

Body parameter

{
  "display_name": "string",
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "regenerate_token": true
}

Parameters

Name In Type Required Description
workspaceproxy path string(uuid) true Proxy ID or name
body body codersdk.PatchWorkspaceProxy true Update workspace proxy request

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "deleted": true,
  "derp_enabled": true,
  "derp_only": true,
  "display_name": "string",
  "healthy": true,
  "icon_url": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "string",
  "path_app_url": "string",
  "status": {
    "checked_at": "2019-08-24T14:15:22Z",
    "report": {
      "errors": [
        "string"
      ],
      "warnings": [
        "string"
      ]
    },
    "status": "ok"
  },
  "updated_at": "2019-08-24T14:15:22Z",
  "version": "string",
  "wildcard_hostname": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.WorkspaceProxy

To perform this operation, you must be authenticated. Learn more.

Get workspace external agent credentials

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/workspaces/{workspace}/external-agent/{agent}/credentials \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/workspaces/{workspace}/external-agent/{agent}/credentials

Parameters

Name In Type Required Description
workspace path string(uuid) true Workspace ID
agent path string true Agent name

Example responses

200 Response

{
  "agent_token": "string",
  "command": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.ExternalAgentCredentials

To perform this operation, you must be authenticated. Learn more.

OAuth2 authorization request (GET - show authorization page)

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/oauth2/authorize?client_id=string&response_type=code&code_challenge=string \
  -H 'Coder-Session-Token: API_KEY'

GET /oauth2/authorize

Parameters

Name In Type Required Description
client_id query string true Client ID
state query string false A random unguessable string, echoed back on the callback
response_type query string true Response type
redirect_uri query string false Redirect here after authorization
scope query string false Space-separated scopes to request. Each must be supported by this deployment, and the app's allowlist, when it has one, must cover the permissions requested rather than name each scope. Defaults to that allowlist, or to coder:all for an app with no allowlist
code_challenge query string true PKCE code challenge, 43 to 128 characters from [A-Za-z0-9-._~] (RFC 7636)
code_challenge_method query string false PKCE challenge method. S256 only; omitting it means S256
resource query string false RFC 8707 resource indicator: an absolute URI without a fragment

Enumerated Values

Parameter Value(s)
response_type code
code_challenge_method S256

Responses

Status Meaning Description Schema
200 OK Returns HTML authorization page
302 Found Redirects to the app's registered callback carrying an OAuth2 error (RFC 6749 4.1.2.1)
400 Bad Request HTML error page. The failure names the redirect URI or the client, so RFC 6749 4.1.2.1 withholds the callback
500 Internal Server Error HTML error page. One of the app's registered redirect URIs is not usable

To perform this operation, you must be authenticated. Learn more.

OAuth2 authorization request (POST - process authorization)

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/oauth2/authorize?client_id=string&response_type=code&code_challenge=string \
  -H 'Accept: application/json' \
  -H 'Coder-Session-Token: API_KEY'

POST /oauth2/authorize

Parameters

Name In Type Required Description
client_id query string true Client ID
state query string false A random unguessable string, echoed back on the callback
response_type query string true Response type
redirect_uri query string false Redirect here after authorization
scope query string false Space-separated scopes to request. Each must be supported by this deployment, and the app's allowlist, when it has one, must cover the permissions requested rather than name each scope. Defaults to that allowlist, or to coder:all for an app with no allowlist
code_challenge query string true PKCE code challenge, 43 to 128 characters from [A-Za-z0-9-._~] (RFC 7636)
code_challenge_method query string false PKCE challenge method. S256 only; omitting it means S256
resource query string false RFC 8707 resource indicator: an absolute URI without a fragment

Enumerated Values

Parameter Value(s)
response_type code
code_challenge_method S256

Example responses

400 Response

{
  "error": "invalid_request",
  "error_description": "string",
  "error_uri": "string"
}

Responses

Status Meaning Description Schema
302 Found Redirects to the app's registered callback carrying either an authorization code or an OAuth2 error (RFC 6749 4.1.2.1)
400 Bad Request The failure names the redirect URI or the client, so RFC 6749 4.1.2.1 withholds the callback codersdk.OAuth2Error
500 Internal Server Error One of the app's registered redirect URIs is not usable codersdk.OAuth2Error

To perform this operation, you must be authenticated. Learn more.

Get OAuth2 client configuration (RFC 7592)

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/oauth2/clients/{client_id} \
  -H 'Accept: application/json'

GET /oauth2/clients/{client_id}

Parameters

Name In Type Required Description
client_id path string true Client ID

Example responses

200 Response

{
  "client_id": "string",
  "client_id_issued_at": 0,
  "client_name": "string",
  "client_secret_expires_at": 0,
  "client_uri": "string",
  "contacts": [
    "string"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "jwks": {},
  "jwks_uri": "string",
  "logo_uri": "string",
  "policy_uri": "string",
  "redirect_uris": [
    "string"
  ],
  "registration_access_token": "string",
  "registration_client_uri": "string",
  "response_types": [
    "code"
  ],
  "scope": "string",
  "software_id": "string",
  "software_version": "string",
  "token_endpoint_auth_method": "client_secret_basic",
  "tos_uri": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2ClientConfiguration

Update OAuth2 client configuration (RFC 7592)

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/oauth2/clients/{client_id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

PUT /oauth2/clients/{client_id}

Body parameter

{
  "client_name": "string",
  "client_uri": "string",
  "contacts": [
    "string"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "jwks": {},
  "jwks_uri": "string",
  "logo_uri": "string",
  "policy_uri": "string",
  "redirect_uris": [
    "string"
  ],
  "response_types": [
    "code"
  ],
  "scope": "string",
  "software_id": "string",
  "software_statement": "string",
  "software_version": "string",
  "token_endpoint_auth_method": "client_secret_basic",
  "tos_uri": "string"
}

Parameters

Name In Type Required Description
client_id path string true Client ID
body body codersdk.OAuth2ClientRegistrationRequest true Client update request

Example responses

200 Response

{
  "client_id": "string",
  "client_id_issued_at": 0,
  "client_name": "string",
  "client_secret_expires_at": 0,
  "client_uri": "string",
  "contacts": [
    "string"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "jwks": {},
  "jwks_uri": "string",
  "logo_uri": "string",
  "policy_uri": "string",
  "redirect_uris": [
    "string"
  ],
  "registration_access_token": "string",
  "registration_client_uri": "string",
  "response_types": [
    "code"
  ],
  "scope": "string",
  "software_id": "string",
  "software_version": "string",
  "token_endpoint_auth_method": "client_secret_basic",
  "tos_uri": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2ClientConfiguration
413 Payload Too Large Request body exceeds 4 MiB codersdk.OAuth2Error

Delete OAuth2 client registration (RFC 7592)

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/oauth2/clients/{client_id}

DELETE /oauth2/clients/{client_id}

Parameters

Name In Type Required Description
client_id path string true Client ID

Responses

Status Meaning Description Schema
204 No Content No Content

OAuth2 dynamic client registration (RFC 7591)

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/oauth2/register \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST /oauth2/register

Body parameter

{
  "client_name": "string",
  "client_uri": "string",
  "contacts": [
    "string"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "jwks": {},
  "jwks_uri": "string",
  "logo_uri": "string",
  "policy_uri": "string",
  "redirect_uris": [
    "string"
  ],
  "response_types": [
    "code"
  ],
  "scope": "string",
  "software_id": "string",
  "software_statement": "string",
  "software_version": "string",
  "token_endpoint_auth_method": "client_secret_basic",
  "tos_uri": "string"
}

Parameters

Name In Type Required Description
body body codersdk.OAuth2ClientRegistrationRequest true Client registration request

Example responses

201 Response

{
  "client_id": "string",
  "client_id_issued_at": 0,
  "client_name": "string",
  "client_secret": "string",
  "client_secret_expires_at": 0,
  "client_uri": "string",
  "contacts": [
    "string"
  ],
  "grant_types": [
    "authorization_code"
  ],
  "jwks": {},
  "jwks_uri": "string",
  "logo_uri": "string",
  "policy_uri": "string",
  "redirect_uris": [
    "string"
  ],
  "registration_access_token": "string",
  "registration_client_uri": "string",
  "response_types": [
    "code"
  ],
  "scope": "string",
  "software_id": "string",
  "software_version": "string",
  "token_endpoint_auth_method": "client_secret_basic",
  "tos_uri": "string"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.OAuth2ClientRegistrationResponse
413 Payload Too Large Request body exceeds 4 MiB codersdk.OAuth2Error

Revoke OAuth2 tokens (RFC 7009)

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/oauth2/revoke \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ='

POST /oauth2/revoke

Body parameter

client_id: string
client_secret: string
token: string
token_type_hint: string

Parameters

Name In Type Required Description
Authorization header string false HTTP Basic credentials, the client_id as the username and the client_secret as the password. A confidential client sends these or the form fields below, not both.
body body object false
» client_id body string false Client ID, required unless sent as the HTTP Basic username
» client_secret body string false Client secret, required for a confidential client unless sent as the HTTP Basic password. Public clients (token_endpoint_auth_method=none) send no secret.
» token body string true The token to revoke
» token_type_hint body string false Hint about token type (access_token or refresh_token)

Example responses

400 Response

{
  "error": "invalid_request",
  "error_description": "string",
  "error_uri": "string"
}

Responses

Status Meaning Description Schema
200 OK Token successfully revoked. A 200 does not confirm that the token existed or belonged to the client
400 Bad Request invalid_request: a missing client_id or token, credentials in both the Authorization header and the body, client_secret in the URL query string, or a malformed token codersdk.OAuth2Error
401 Unauthorized invalid_client: the client is unknown, or a confidential client did not present a valid secret codersdk.OAuth2Error
413 Payload Too Large Request body exceeds 4 MiB codersdk.OAuth2Error

OAuth2 token exchange

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/oauth2/tokens \
  -H 'Accept: application/json'

POST /oauth2/tokens

Body parameter

client_id: string
client_secret: string
code: string
code_verifier: string
refresh_token: string
grant_type: authorization_code

Parameters

Name In Type Required Description
body body object false
» client_id body string false Client ID, required if grant_type=authorization_code
» client_secret body string false Client secret, required if grant_type=authorization_code and the client is confidential. Public clients (token_endpoint_auth_method=none) send no secret.
» code body string false Authorization code, required if grant_type=authorization_code
» code_verifier body string false PKCE code verifier, required if grant_type=authorization_code. 43-128 characters per RFC 7636.
» refresh_token body string false Refresh token, required if grant_type=refresh_token
» grant_type body string true Grant type

Enumerated Values

Parameter Value(s)
» grant_type authorization_code, client_credentials, implicit, password, refresh_token

Example responses

200 Response

{
  "access_token": "string",
  "expires_in": 0,
  "expiry": "2019-08-24T14:15:22Z",
  "refresh_token": "string",
  "scope": "string",
  "token_type": "Bearer"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OAuth2TokenResponse
400 Bad Request invalid_request: client_secret in the URL query string, or a missing or malformed parameter codersdk.OAuth2Error
413 Payload Too Large Request body exceeds 4 MiB codersdk.OAuth2Error

Delete OAuth2 application tokens

Code samples

# Example request using curl
curl -X DELETE http://coder-server:8080/oauth2/tokens?client_id=string \
  -H 'Coder-Session-Token: API_KEY'

DELETE /oauth2/tokens

Parameters

Name In Type Required Description
client_id query string true Client ID

Responses

Status Meaning Description Schema
204 No Content No Content

To perform this operation, you must be authenticated. Learn more.

SCIM 2.0: Service Provider Config

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/scim/v2/ServiceProviderConfig

GET /scim/v2/ServiceProviderConfig

Responses

Status Meaning Description Schema
200 OK OK

SCIM 2.0: Get users

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/scim/v2/Users \
  -H 'Authorization: API_KEY'

GET /scim/v2/Users

Responses

Status Meaning Description Schema
200 OK OK

To perform this operation, you must be authenticated. Learn more.

SCIM 2.0: Create new user

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/scim/v2/Users \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: API_KEY'

POST /scim/v2/Users

Body parameter

{
  "active": true,
  "emails": [
    {
      "display": "string",
      "primary": true,
      "type": "string",
      "value": "user@example.com"
    }
  ],
  "groups": [
    null
  ],
  "id": "string",
  "meta": {
    "resourceType": "string"
  },
  "name": {
    "familyName": "string",
    "givenName": "string"
  },
  "schemas": [
    "string"
  ],
  "userName": "string"
}

Parameters

Name In Type Required Description
body body legacyscim.SCIMUser true New user

Example responses

200 Response

{
  "active": true,
  "emails": [
    {
      "display": "string",
      "primary": true,
      "type": "string",
      "value": "user@example.com"
    }
  ],
  "groups": [
    null
  ],
  "id": "string",
  "meta": {
    "resourceType": "string"
  },
  "name": {
    "familyName": "string",
    "givenName": "string"
  },
  "schemas": [
    "string"
  ],
  "userName": "string"
}

Responses

Status Meaning Description Schema
200 OK OK legacyscim.SCIMUser

To perform this operation, you must be authenticated. Learn more.

SCIM 2.0: Get user by ID

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/scim/v2/Users/{id} \
  -H 'Authorization: API_KEY'

GET /scim/v2/Users/{id}

Parameters

Name In Type Required Description
id path string(uuid) true User ID

Responses

Status Meaning Description Schema
404 Not Found Not Found

To perform this operation, you must be authenticated. Learn more.

SCIM 2.0: Replace user account

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/scim/v2/Users/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/scim+json' \
  -H 'Authorization: API_KEY'

PUT /scim/v2/Users/{id}

Body parameter

{
  "active": true,
  "emails": [
    {
      "display": "string",
      "primary": true,
      "type": "string",
      "value": "user@example.com"
    }
  ],
  "groups": [
    null
  ],
  "id": "string",
  "meta": {
    "resourceType": "string"
  },
  "name": {
    "familyName": "string",
    "givenName": "string"
  },
  "schemas": [
    "string"
  ],
  "userName": "string"
}

Parameters

Name In Type Required Description
id path string(uuid) true User ID
body body legacyscim.SCIMUser true Replace user request

Example responses

200 Response

{
  "avatar_url": "http://example.com",
  "created_at": "2019-08-24T14:15:22Z",
  "email": "user@example.com",
  "has_ai_seat": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "is_service_account": true,
  "last_seen_at": "2019-08-24T14:15:22Z",
  "login_type": "",
  "name": "string",
  "organization_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "roles": [
    {
      "display_name": "string",
      "name": "string",
      "organization_id": "string"
    }
  ],
  "status": "active",
  "theme_preference": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "username": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.User

To perform this operation, you must be authenticated. Learn more.

SCIM 2.0: Update user account

Code samples

# Example request using curl
curl -X PATCH http://coder-server:8080/scim/v2/Users/{id} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/scim+json' \
  -H 'Authorization: API_KEY'

PATCH /scim/v2/Users/{id}

Body parameter

{
  "active": true,
  "emails": [
    {
      "display": "string",
      "primary": true,
      "type": "string",
      "value": "user@example.com"
    }
  ],
  "groups": [
    null
  ],
  "id": "string",
  "meta": {
    "resourceType": "string"
  },
  "name": {
    "familyName": "string",
    "givenName": "string"
  },
  "schemas": [
    "string"
  ],
  "userName": "string"
}

Parameters

Name In Type Required Description
id path string(uuid) true User ID
body body legacyscim.SCIMUser true Update user request

Example responses

200 Response

{
  "avatar_url": "http://example.com",
  "created_at": "2019-08-24T14:15:22Z",
  "email": "user@example.com",
  "has_ai_seat": true,
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "is_service_account": true,
  "last_seen_at": "2019-08-24T14:15:22Z",
  "login_type": "",
  "name": "string",
  "organization_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "roles": [
    {
      "display_name": "string",
      "name": "string",
      "organization_id": "string"
    }
  ],
  "status": "active",
  "theme_preference": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "username": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.User

To perform this operation, you must be authenticated. Learn more.