# Authorization

## List API key scopes [#list-api-key-scopes]

### Code samples [#code-samples]

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

`GET /api/v2/auth/scopes`

### Example responses [#example-responses]

> 200 Response

```json
{
  "external": [
    "all"
  ]
}
```

### Responses [#responses]

| Status | Meaning                                                 | Description | Schema                                                                                          |
| ------ | ------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.ExternalAPIKeyScopes](/beta-docs/reference/api/schemas/#codersdkexternalapikeyscopes) |

## Check authorization [#check-authorization]

### Code samples [#code-samples-1]

```sh
# 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 /api/v2/authcheck`

> Body parameter

```json
{
  "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 [#parameters]

| Name   | In   | Type                                                                                            | Required | Description           |
| ------ | ---- | ----------------------------------------------------------------------------------------------- | -------- | --------------------- |
| `body` | body | [codersdk.AuthorizationRequest](/beta-docs/reference/api/schemas/#codersdkauthorizationrequest) | true     | Authorization request |

### Example responses [#example-responses-1]

> 200 Response

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

### Responses [#responses-1]

| Status | Meaning                                                 | Description | Schema                                                                                            |
| ------ | ------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.AuthorizationResponse](/beta-docs/reference/api/schemas/#codersdkauthorizationresponse) |

To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).

## Log in user [#log-in-user]

### Code samples [#code-samples-2]

```sh
# 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 /api/v2/users/login`

> Body parameter

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

### Parameters [#parameters-1]

| Name   | In   | Type                                                                                                    | Required | Description   |
| ------ | ---- | ------------------------------------------------------------------------------------------------------- | -------- | ------------- |
| `body` | body | [codersdk.LoginWithPasswordRequest](/beta-docs/reference/api/schemas/#codersdkloginwithpasswordrequest) | true     | Login request |

### Example responses [#example-responses-2]

> 201 Response

```json
{
  "session_token": "string"
}
```

### Responses [#responses-2]

| Status | Meaning                                                      | Description | Schema                                                                                                    |
| ------ | ------------------------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------- |
| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created     | [codersdk.LoginWithPasswordResponse](/beta-docs/reference/api/schemas/#codersdkloginwithpasswordresponse) |

## Change password with a one-time passcode [#change-password-with-a-one-time-passcode]

### Code samples [#code-samples-3]

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

`POST /api/v2/users/otp/change-password`

> Body parameter

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

### Parameters [#parameters-2]

| Name   | In   | Type                                                                                                                                    | Required | Description             |
| ------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------- |
| `body` | body | [codersdk.ChangePasswordWithOneTimePasscodeRequest](/beta-docs/reference/api/schemas/#codersdkchangepasswordwithonetimepasscoderequest) | true     | Change password request |

### Responses [#responses-3]

| Status | Meaning                                                         | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | ------ |
| 204    | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content  |        |

## Request one-time passcode [#request-one-time-passcode]

### Code samples [#code-samples-4]

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

`POST /api/v2/users/otp/request`

> Body parameter

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

### Parameters [#parameters-3]

| Name   | In   | Type                                                                                                              | Required | Description               |
| ------ | ---- | ----------------------------------------------------------------------------------------------------------------- | -------- | ------------------------- |
| `body` | body | [codersdk.RequestOneTimePasscodeRequest](/beta-docs/reference/api/schemas/#codersdkrequestonetimepasscoderequest) | true     | One-time passcode request |

### Responses [#responses-4]

| Status | Meaning                                                         | Description | Schema |
| ------ | --------------------------------------------------------------- | ----------- | ------ |
| 204    | [No Content](https://tools.ietf.org/html/rfc7231#section-6.3.5) | No Content  |        |

## Validate user password [#validate-user-password]

### Code samples [#code-samples-5]

```sh
# 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 /api/v2/users/validate-password`

> Body parameter

```json
{
  "password": "string"
}
```

### Parameters [#parameters-4]

| Name   | In   | Type                                                                                                          | Required | Description                    |
| ------ | ---- | ------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------ |
| `body` | body | [codersdk.ValidateUserPasswordRequest](/beta-docs/reference/api/schemas/#codersdkvalidateuserpasswordrequest) | true     | Validate user password request |

### Example responses [#example-responses-3]

> 200 Response

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

### Responses [#responses-5]

| Status | Meaning                                                 | Description | Schema                                                                                                          |
| ------ | ------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------- |
| 200    | [OK](https://tools.ietf.org/html/rfc7231#section-6.3.1) | OK          | [codersdk.ValidateUserPasswordResponse](/beta-docs/reference/api/schemas/#codersdkvalidateuserpasswordresponse) |

To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).

## Convert user from password to oauth authentication [#convert-user-from-password-to-oauth-authentication]

### Code samples [#code-samples-6]

```sh
# 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 /api/v2/users/{user}/convert-login`

> Body parameter

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

### Parameters [#parameters-5]

| Name   | In   | Type                                                                                          | Required | Description          |
| ------ | ---- | --------------------------------------------------------------------------------------------- | -------- | -------------------- |
| `user` | path | string                                                                                        | true     | User ID, name, or me |
| `body` | body | [codersdk.ConvertLoginRequest](/beta-docs/reference/api/schemas/#codersdkconvertloginrequest) | true     | Convert request      |

### Example responses [#example-responses-4]

> 201 Response

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

### Responses [#responses-6]

| Status | Meaning                                                      | Description | Schema                                                                                                |
| ------ | ------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------- |
| 201    | [Created](https://tools.ietf.org/html/rfc7231#section-6.3.2) | Created     | [codersdk.OAuthConversionResponse](/beta-docs/reference/api/schemas/#codersdkoauthconversionresponse) |

To perform this operation, you must be authenticated. [Learn more](/beta-docs/reference/api/authentication/).