Files
coder/docs/reference/api/users.md
T
Michael Suchacz b67587c875 feat: add the organization skills data model (#30609)
## Stack

Part of
[CODAGT-1341](https://linear.app/codercom/issue/CODAGT-1341/support-organization-level-skills-in-coder-agents).
This stack adds organization skills to Coder Agents: admins publish a
skill once per organization, share it with groups or members, and chats
in that organization load it next to personal and workspace skills. It
replaces the 21-PR draft stack #30584 to #30604 with five PRs, bottom to
top:

1. **#30609** data model: one migration, queries, RBAC and dbauthz (this
PR)
2. #30610 organization skill API routes and the scope-neutral SDK
3. #30611 sharing ACL routes
4. #30612 settings UI: shared skills table, admin page, member section
5. #30613 chats: chatd loading, `/` menu, docs

## What changes

This PR adds the data model and authorization for organization skills.
Personal skills keep working unchanged: `git diff origin/main --
codersdk site` shows only generated RBAC and API key scope additions
(`apikey_scopes_gen.go`, `rbacresources_gen.go`,
`rbacresourcesGenerated.ts`, the RBAC and scope unions in
`typesGenerated.ts`) and `codersdk.ResourceTypeOrganizationSkill` with
its friendly string. No personal route, SDK type or site component
changes, and `coderd/userskills_test.go` changes only by mechanical
constant renames.

**One migration, `000621_skills`** (please review it closely):

- renames `user_skills` to `skills` with its constraints, index and
triggers, and recreates the cap function and
`delete_deleted_user_resources`, whose PL/pgSQL bodies name the table;
- adds `organization_id` and `project_id` (`ON DELETE CASCADE`),
`enabled` (default true), and `group_acl` / `user_acl` (`jsonb`, default
`{}`), with CHECKs for exactly one owner, ACLs that are JSON objects,
and ACLs that stay empty unless an organization owns the row, plus
partial unique name indexes per owner kind;
- replaces the cap trigger with `enforce_skills_per_owner_limit()`: 100
rows per owner, disabled rows included, locking the owner row `FOR NO
KEY UPDATE` so unrelated foreign key checks are not blocked;
- adds a `BEFORE DELETE` trigger on `organization_members` that removes
a departing member from `user_acl` on that organization's skills, so
rejoining doesn't restore a direct grant;
- adds the `organization_skill` `resource_type` and `api_key_scope` enum
values last; nothing in the migration uses them.

The down migration undoes the three old migrations in reverse order: it
drops organization and project rows and restores `user_skills`, its
names, the cap function and `user_id NOT NULL`.

Authorization: a new RBAC resource `organization_skill` (create, read,
update, delete, share). Owner and org admin get it; site and org
auditors get read; members read only through the skill's ACL, which
applies only to members of its organization. `Skill.RBACObject()`
returns the organization object with both ACLs; project rows stay denied
to everyone. New sqlc queries cover organization insert, get, list
(SQL-filtered through `GetAuthorizedOrganizationSkillMetadata` and a
`regosql` converter), update and delete, with dbauthz wrappers and the
audit table entries. No routes yet.

## Commits

The first commit reproduces the reviewed code from the old stack; each
later commit is a labeled trim or fix.

- `baa3150e3b7` feat: add the organization skills data model.
Reproduction: every non-site file this commit changes equals the
reviewed old `authz` head `1e16b3004c4`, except that the old stack's
migrations 000615, 000616 and 000617 are merged into one migration (then
`000615_skills`, now `000621_skills`) with one fixture
(`testdata/fixtures/000621_skills.up.sql`) and one migration test (now
`testMigration000621Skills`). At that commit, `dump.sql` was
byte-identical to the old head's.
- `1b84e83463a` test(coderd/database): keep only the SQL paths of the
org skill matrix. `TestOrganizationSkillAuthorization` becomes
`TestOrganizationSkillQueries` instead of being deleted, because
coverage showed it is this PR's only run of the
`GetAuthorizedOrganizationSkillMetadata` row scan (80% to 65% without
it) and of the organization update and delete queries (100% to 0%).
Swapping `group_acl` and `user_acl` in the converter makes
`GrantedMember` fail. The removed cases are decided by
`TestRolePermissions`, `TestSkillRBACObjectOrganizationACL` and the
dbauthz method suite.
- `e2931b412e9` test(coderd/database): fold the skill cap cases into
existing coverage. The user case is covered by `TestUserSkillLimit` and
`TestUserSkillLimitConcurrentCreates`; the organization case folds into
`ConcurrentOrganizationInsertsHonorCap`, which now also checks that
disabled rows count and another organization is unaffected (mutation
checked); the project case stays.
- `be62aea9021` test(coderd/rbac): drop
`TestOrganizationSkillReadScope`, covered by `TestExternalScopeNames`
and the generated scope file.
- `0c275ba37de` merges main at `454a2fcc697`, which took 000615 to
000618: it renumbers the migration to 000619 and resolves `dump.sql`,
`check_constraint.go` and the generated API docs. `8f2b4b87ee2` merges
main at `ad85646164e`, which took 000619: it renumbers the migration to
000620.
- `5248d56b64f` merges main at `e7b76872098`, which took 000620
(`000620_audit_chat_project_instructions_resource_type`): it renumbers
the migration, fixture and migration test to `000621_skills` (step
`Migration000621Skills`, version 621), and resolves
`enterprise/audit/table.go` (keeping main's
`AuditableChatProjectInstructions` entries and the `Skill` entry),
`dump.sql` and `models.go` (the `resource_type` enum gets
`chat_project_instructions`, then `organization_skill`) and the
regenerated `schemas.md`. The up and down SQL are unchanged by every
renumbering.

## Size

Production +549/-67, tests +728/-33, generated +881/-314; total
+2158/-414. This is above the 500-line reviewer-friendly limit on
purpose: Mike asked for 4 to 5 PRs instead of the 21 small ones this
stack replaces.

## Replaces

#30584 (rename `user_skills` to `skills`), #30585 (skill owners), #30586
(organization skill authorization).

## Validation

- Migration test: up keeps the existing personal row and its ID; down
restores the `user_skills` names, cap function and `NOT NULL`, and drops
organization rows; soft-deleting a user removes their skills after up,
after down, and after re-up.
- `go test` passed on `be62aea9021`, before the main merges, for
`coderd` (skill tests), `coderd/database`, `dbauthz`, `migrations`,
`gentest`, `coderd/rbac/...`, `coderd/x/chatd`, `coderd/x/skills`,
`enterprise/audit` and `enterprise/coderd`; `make lint/check-scopes`
passed; the four personal skills Vitest files pass unchanged.
- On `5248d56b64f`: build, vet, `TestMigrate`, `TestMigrationChain`, the
`migrations`, `database`, `dbauthz`, `gentest`, `rbac` and
`enterprise/audit` packages pass; `make gen` run twice is clean, and
`make pre-commit` passes.
- Remote UAT round 7 through Coder Agents passed on the whole stack; see
#30613's Validation for scope and findings.

> Xum opened this PR on behalf of @ibetitsmike.
2026-10-13 15:51:31 +00:00

57 KiB
Generated

title
title
Users

Get users

Code samples

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

GET /api/v2/users

Parameters

Name In Type Required Description
q query string false 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",
      "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.GetUsersResponse

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

Create new user

Code samples

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

POST /api/v2/users

Body parameter

{
  "email": "user@example.com",
  "login_type": "",
  "name": "string",
  "organization_ids": [
    "497f6eca-6276-4993-bfeb-53cbbbba6f08"
  ],
  "password": "string",
  "roles": [
    "string"
  ],
  "service_account": true,
  "user_status": "active",
  "username": "string"
}

Parameters

Name In Type Required Description
body body codersdk.CreateUserRequest true Create user request

Example responses

201 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
201 Created Created codersdk.User

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

Get authentication methods

Code samples

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

GET /api/v2/users/authmethods

Example responses

200 Response

{
  "github": {
    "default_provider_configured": true,
    "enabled": true
  },
  "oidc": {
    "enabled": true,
    "iconUrl": "string",
    "signInText": "string"
  },
  "password": {
    "enabled": true
  },
  "terms_of_service_url": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.AuthMethods

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

Check initial user created

Code samples

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

GET /api/v2/users/first

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.

Create initial user

Code samples

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

POST /api/v2/users/first

Body parameter

{
  "email": "string",
  "name": "string",
  "onboarding_info": {
    "newsletter_marketing": true,
    "newsletter_releases": true
  },
  "password": "string",
  "trial": true,
  "trial_info": {
    "company_name": "string",
    "country": "string",
    "developers": "string",
    "first_name": "string",
    "job_title": "string",
    "last_name": "string",
    "phone_number": "string"
  },
  "username": "string"
}

Parameters

Name In Type Required Description
body body codersdk.CreateFirstUserRequest true First user request

Example responses

201 Response

{
  "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.CreateFirstUserResponse

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

Log out user

Code samples

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

POST /api/v2/users/logout

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.

OAuth 2.0 GitHub Callback

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/oauth2/github/callback \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/users/oauth2/github/callback

Responses

Status Meaning Description Schema
307 Temporary Redirect Temporary Redirect

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

Get Github device auth

Code samples

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

GET /api/v2/users/oauth2/github/device

Example responses

200 Response

{
  "device_code": "string",
  "expires_in": 0,
  "interval": 0,
  "user_code": "string",
  "verification_uri": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.ExternalAuthDevice

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

Get OIDC claims for the authenticated user

Code samples

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

GET /api/v2/users/oidc-claims

Example responses

200 Response

{
  "claims": {}
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.OIDCClaimsResponse

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

OpenID Connect Callback

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/users/oidc/callback \
  -H 'Coder-Session-Token: API_KEY'

GET /api/v2/users/oidc/callback

Responses

Status Meaning Description Schema
307 Temporary Redirect Temporary Redirect

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

Get user by name

Code samples

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

GET /api/v2/users/{user}

Parameters

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

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.

Delete user

Code samples

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

DELETE /api/v2/users/{user}

Parameters

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

Responses

Status Meaning Description Schema
200 OK OK

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

Get user appearance settings

Code samples

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

GET /api/v2/users/{user}/appearance

Parameters

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

Example responses

200 Response

{
  "terminal_font": "",
  "theme_dark": "string",
  "theme_light": "string",
  "theme_mode": "",
  "theme_preference": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UserAppearanceSettings

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

Update user appearance settings

Code samples

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

PUT /api/v2/users/{user}/appearance

Body parameter

{
  "terminal_font": "",
  "theme_dark": "light",
  "theme_light": "light",
  "theme_mode": "sync",
  "theme_preference": "string"
}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
body body codersdk.UpdateUserAppearanceSettingsRequest true New appearance settings

Example responses

200 Response

{
  "terminal_font": "",
  "theme_dark": "string",
  "theme_light": "string",
  "theme_mode": "",
  "theme_preference": "string"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UserAppearanceSettings

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

Get user Git SSH key

Code samples

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

GET /api/v2/users/{user}/gitsshkey

Parameters

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

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "public_key": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GitSSHKey

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

Regenerate user SSH key

Code samples

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

PUT /api/v2/users/{user}/gitsshkey

Parameters

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

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "public_key": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.GitSSHKey

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

Create new session key

Code samples

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

POST /api/v2/users/{user}/keys

Parameters

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

Example responses

201 Response

{
  "key": "string"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.GenerateAPIKeyResponse

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

Get user tokens

Code samples

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

GET /api/v2/users/{user}/keys/tokens

Parameters

Name In Type Required Description
user path string true User ID, name, or me
include_expired query boolean false Include expired tokens in the list

Example responses

200 Response

[
  {
    "allow_list": [
      {
        "id": "string",
        "type": "*"
      }
    ],
    "created_at": "2019-08-24T14:15:22Z",
    "expires_at": "2019-08-24T14:15:22Z",
    "id": "string",
    "last_used": "2019-08-24T14:15:22Z",
    "lifetime_seconds": 0,
    "login_type": "password",
    "scope": "all",
    "scopes": [
      "all"
    ],
    "token_name": "string",
    "updated_at": "2019-08-24T14:15:22Z",
    "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
  }
]

Responses

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

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» allow_list array false
»» id string false
»» type codersdk.RBACResource false
» created_at string(date-time) true
» expires_at string(date-time) true
» id string true
» last_used string(date-time) true
» lifetime_seconds integer true
» login_type codersdk.LoginType true
» scope codersdk.APIKeyScope false Deprecated: use Scopes instead.
» scopes array false
» token_name string true
» updated_at string(date-time) true
» user_id string(uuid) true

Enumerated Values

Property Value(s)
type *, ai_gateway_key, ai_model_price, ai_provider, ai_seat, aibridge_interception, api_key, assign_org_role, assign_role, audit_log, boundary_log, boundary_usage, chat, chat_model_config, chat_project, chat_project_memory, connection_log, crypto_key, debug_info, deployment_config, deployment_stats, file, group, group_member, idpsync_settings, inbox_notification, license, mcp_server_config, notification_message, notification_preference, notification_template, oauth2_app, oauth2_app_code_token, oauth2_app_secret, organization, organization_member, organization_skill, prebuilt_workspace, provisioner_daemon, provisioner_jobs, replicas, system, tailnet_coordinator, template, usage_event, user, user_secret, user_skill, webpush_subscription, workspace, workspace_agent_devcontainers, workspace_agent_resource_monitor, workspace_build_orchestration, workspace_dormant, workspace_proxy
login_type github, oidc, password, token
scope all, application_connect

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

Create token API key

Code samples

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

POST /api/v2/users/{user}/keys/tokens

Body parameter

{
  "allow_list": [
    {
      "id": "string",
      "type": "*"
    }
  ],
  "lifetime": 0,
  "scope": "all",
  "scopes": [
    "all"
  ],
  "token_name": "string"
}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
body body codersdk.CreateTokenRequest true Create token request

Example responses

201 Response

{
  "key": "string"
}

Responses

Status Meaning Description Schema
201 Created Created codersdk.GenerateAPIKeyResponse

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

Get API key by token name

Code samples

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

GET /api/v2/users/{user}/keys/tokens/{keyname}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
keyname path string(string) true Key Name

Example responses

200 Response

{
  "allow_list": [
    {
      "id": "string",
      "type": "*"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "id": "string",
  "last_used": "2019-08-24T14:15:22Z",
  "lifetime_seconds": 0,
  "login_type": "password",
  "scope": "all",
  "scopes": [
    "all"
  ],
  "token_name": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.APIKey

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

Get API key by ID

Code samples

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

GET /api/v2/users/{user}/keys/{keyid}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
keyid path string(string) true Key ID

Example responses

200 Response

{
  "allow_list": [
    {
      "id": "string",
      "type": "*"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "expires_at": "2019-08-24T14:15:22Z",
  "id": "string",
  "last_used": "2019-08-24T14:15:22Z",
  "lifetime_seconds": 0,
  "login_type": "password",
  "scope": "all",
  "scopes": [
    "all"
  ],
  "token_name": "string",
  "updated_at": "2019-08-24T14:15:22Z",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.APIKey

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

Delete API key

Code samples

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

DELETE /api/v2/users/{user}/keys/{keyid}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
keyid path string(string) true Key ID

Responses

Status Meaning Description Schema
204 No Content No Content

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

Expire API key

Code samples

# Example request using curl
curl -X PUT http://coder-server:8080/api/v2/users/{user}/keys/{keyid}/expire \
  -H 'Accept: */*' \
  -H 'Coder-Session-Token: API_KEY'

PUT /api/v2/users/{user}/keys/{keyid}/expire

Parameters

Name In Type Required Description
user path string true User ID, name, or me
keyid path string(string) true Key ID

Example responses

404 Response

Responses

Status Meaning Description Schema
204 No Content No Content
404 Not Found Not Found codersdk.Response
500 Internal Server Error Internal Server Error codersdk.Response

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

Get user login type

Code samples

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

GET /api/v2/users/{user}/login-type

Parameters

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

Example responses

200 Response

{
  "login_type": ""
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UserLoginType

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

Get organizations by user

Code samples

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

GET /api/v2/users/{user}/organizations

Parameters

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

Example responses

200 Response

[
  {
    "created_at": "2019-08-24T14:15:22Z",
    "default_org_member_roles": [
      "string"
    ],
    "description": "string",
    "display_name": "string",
    "icon": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "is_default": true,
    "name": "string",
    "updated_at": "2019-08-24T14:15:22Z"
  }
]

Responses

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

Response Schema

Status Code 200

Name Type Required Restrictions Description
[array item] array false
» created_at string(date-time) true
» default_org_member_roles array false Default org member roles are unioned into every member's effective roles at request time. Changes propagate to all members on the next request.
» description string false
» display_name string false
» icon string false
» id string(uuid) true
» is_default boolean true
» name string false
» updated_at string(date-time) true

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

Get organization by user and organization name

Code samples

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

GET /api/v2/users/{user}/organizations/{organizationname}

Parameters

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

Example responses

200 Response

{
  "created_at": "2019-08-24T14:15:22Z",
  "default_org_member_roles": [
    "string"
  ],
  "description": "string",
  "display_name": "string",
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "is_default": true,
  "name": "string",
  "updated_at": "2019-08-24T14:15:22Z"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.Organization

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

Update user password

Code samples

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

PUT /api/v2/users/{user}/password

Body parameter

{
  "old_password": "string",
  "password": "string"
}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
body body codersdk.UpdateUserPasswordRequest true Update password request

Responses

Status Meaning Description Schema
204 No Content No Content

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

Get user preference settings

Code samples

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

GET /api/v2/users/{user}/preferences

Parameters

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

Example responses

200 Response

{
  "agent_chat_send_shortcut": "enter",
  "code_diff_display_mode": "auto",
  "collapse_assistant_steps": true,
  "shell_tool_display_mode": "auto",
  "thinking_display_mode": "auto"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UserPreferenceSettings

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

Update user preference settings

Code samples

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

PUT /api/v2/users/{user}/preferences

Body parameter

{
  "agent_chat_send_shortcut": "enter",
  "code_diff_display_mode": "auto",
  "collapse_assistant_steps": true,
  "shell_tool_display_mode": "auto",
  "thinking_display_mode": "auto"
}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
body body codersdk.UpdateUserPreferenceSettingsRequest true New preference settings

Example responses

200 Response

{
  "agent_chat_send_shortcut": "enter",
  "code_diff_display_mode": "auto",
  "collapse_assistant_steps": true,
  "shell_tool_display_mode": "auto",
  "thinking_display_mode": "auto"
}

Responses

Status Meaning Description Schema
200 OK OK codersdk.UserPreferenceSettings

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

Update user profile

Code samples

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

PUT /api/v2/users/{user}/profile

Body parameter

{
  "avatar_url": "http://example.com",
  "name": "string",
  "username": "string"
}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
body body codersdk.UpdateUserProfileRequest true Updated profile

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.

Get user roles

Code samples

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

GET /api/v2/users/{user}/roles

Parameters

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

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.

Assign role to user

Code samples

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

PUT /api/v2/users/{user}/roles

Body parameter

{
  "roles": [
    "string"
  ]
}

Parameters

Name In Type Required Description
user path string true User ID, name, or me
body body codersdk.UpdateRoles true Update roles 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.

Activate user account

Code samples

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

PUT /api/v2/users/{user}/status/activate

Parameters

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

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.

Suspend user account

Code samples

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

PUT /api/v2/users/{user}/status/suspend

Parameters

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

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.