mirror of https://github.com/coder/coder.git synced 2026-06-03 13:08:25 +00:00

Files

T

Thomas Kosiewski 4bda39585d feat: add external API key scopes (#19916 )

# Add support for low-level API key scopes

This PR adds support for fine-grained API key scopes based on RBAC resource:action pairs. It includes:

1. A new endpoint `/api/v2/auth/scopes` to list all public low-level API key scopes
2. Generated constants in the SDK for all public scopes
3. Tests to verify scope validation during token creation
4. Updated API documentation to reflect the expanded scope options

The implementation allows users to create API keys with specific permissions like `workspace:read` or `template:use` instead of only the legacy `all` or `application_connect` scopes.



Fixes #19847

2025-09-26 11:43:32 +02:00

9.3 KiB

Generated

Raw Blame History

Authorization

List API key scopes

Code samples

# Example request using curl
curl -X GET http://coder-server:8080/api/v2/auth/scopes \
  -H 'Accept: application/json'

GET /auth/scopes

Example responses

{
  "external": [
    "all"
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.ExternalAPIKeyScopes

Check authorization

Code samples

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

POST /authcheck

{
  "checks": {
    "property1": {
      "action": "create",
      "object": {
        "any_org": true,
        "organization_id": "string",
        "owner_id": "string",
        "resource_id": "string",
        "resource_type": "*"
      }
    },
    "property2": {
      "action": "create",
      "object": {
        "any_org": true,
        "organization_id": "string",
        "owner_id": "string",
        "resource_id": "string",
        "resource_type": "*"
      }
    }
  }
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.AuthorizationRequest	true	Authorization request

Example responses

{
  "property1": true,
  "property2": true
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.AuthorizationResponse

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

Log in user

Code samples

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

POST /users/login

{
  "email": "user@example.com",
  "password": "string"
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.LoginWithPasswordRequest	true	Login request

Example responses

{
  "session_token": "string"
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	codersdk.LoginWithPasswordResponse

Change password with a one-time passcode

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/api/v2/users/otp/change-password \
  -H 'Content-Type: application/json'

POST /users/otp/change-password

{
  "email": "user@example.com",
  "one_time_passcode": "string",
  "password": "string"
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.ChangePasswordWithOneTimePasscodeRequest	true	Change password request

Responses

Status	Meaning	Description	Schema
204	No Content	No Content

Request one-time passcode

Code samples

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

POST /users/otp/request

{
  "email": "user@example.com"
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.RequestOneTimePasscodeRequest	true	One-time passcode request

Responses

Status	Meaning	Description	Schema
204	No Content	No Content

Validate user password

Code samples

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

POST /users/validate-password

{
  "password": "string"
}

Parameters

Name	In	Type	Required	Description
`body`	body	codersdk.ValidateUserPasswordRequest	true	Validate user password request

Example responses

{
  "details": "string",
  "valid": true
}

Responses

Status	Meaning	Description	Schema
200	OK	OK	codersdk.ValidateUserPasswordResponse

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

Convert user from password to oauth authentication

Code samples

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

POST /users/{user}/convert-login

{
  "password": "string",
  "to_type": ""
}

Parameters

Name	In	Type	Required	Description
`user`	path	string	true	User ID, name, or me
`body`	body	codersdk.ConvertLoginRequest	true	Convert request

Example responses

{
  "expires_at": "2019-08-24T14:15:22Z",
  "state_string": "string",
  "to_type": "",
  "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Responses

Status	Meaning	Description	Schema
201	Created	Created	codersdk.OAuthConversionResponse

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

9.3 KiB Generated Raw Blame History

Authorization

List API key scopes

Code samples

Example responses

Responses

Check authorization

Code samples

Parameters

Example responses

Responses

Log in user

Code samples

Parameters

Example responses

Responses

Change password with a one-time passcode

Code samples

Parameters

Responses

Request one-time passcode

Code samples

Parameters

Responses

Validate user password

Code samples

Parameters

Example responses

Responses

Convert user from password to oauth authentication

Code samples

Parameters

Example responses

Responses

9.3 KiB

Generated

Raw Blame History