Files
coder/docs/reference/api/enterprise.md
T
68ca033d67 fix: deliver the rest of the invalid_request class to the client (#28736)
**TL;DR**

Fifth of the stack, split out of #28045. #28450 delivered the errors
raised *after* the callback is trusted and left the parameter failures
behind. This PR delivers those, and replaces the implicit ordering that
decided where an answer went with an explicit classification.

| PR | What it does |
|---|---|
| #28007 | Schema: `codes.scope` and `tokens.scope`, so a negotiated
scope has somewhere to live. |
| #28167 | `ScopesCover` compares an allowlist against a request by
permission coverage rather than by name. |
| #28178 | The authorize endpoint negotiates the scope against the app's
allowlist and persists it on the code. |
| #28179 | The consent page lists the negotiated permissions, and
`invalid_scope` reaches the client's callback. |
| #28450 | The same delivery for every other error raised once the
callback is trusted. |
| **#28736 (this)** | The parameter failures #28450 left behind, and the
classification that decides where each answer goes. |

- Stacked on #28450. Review that first.
- Nothing about what a token can do changes here. This is delivery, not
enforcement.

**Contract change**

A rejected parameter now arrives at the app's registered callback with
`error=invalid_request`, a description naming every failing field, and
the request's `state`. Both verbs.

| Verb | Was |
|---|---|
| GET | static "Invalid Query Parameters" page, 400 |
| POST | `WriteOAuth2Error`, 400 |

An integrator watching for either now reads the error from its own
callback instead.

**Two failures still answer on Coder**, because in neither case is the
callback trustworthy yet:

- A `redirect_uri` that does not parse, or does not exactly match the
registration. Redirecting to it would defeat the check that just
rejected it.
- A `client_id` sent more than once, or naming something other than the
app the callback was matched against. Coder cannot tell whose
registration it is about to redirect to.

An absent query `client_id` is **not** in that group. `httpmw` also
reads the POST form body and the §2.3.1 Basic credential, so an absent
query parameter still names a client and its failure is deliverable.

**Precedence change.** An app whose *registered* callback does not
parse, or uses a rejected scheme, now answers 500 even when the request
also carries parameter errors; that used to answer 400. Decided before
any parameter is read, so the others are never detected. Only reachable
for an app row that bypassed registration.
`DangerousCallbackSchemeOutranksParseFailure` pins it.

**Also in this PR**

- **Unrecognized parameters are ignored**, as §3.1 requires, rather than
rejected by `ErrorExcessParams`. An OIDC `nonce` or a vendor extension
no longer fails the request. Repeats of parameters the endpoint does
read are still rejected.
- **Every unsupported `response_type` gets one code.** Read as text
rather than through the SDK enum, so a value with no Go constant behind
it answers `unsupported_response_type` like `token` does, instead of
splitting on whether the SDK names it.
- **A malformed `resource` answers `invalid_target`** (RFC 8707 §2), but
only when nothing else failed. A client retrying on `invalid_target`
would otherwise resend a request still broken in a field it never heard
about.
- **`error_description` is bounded and readable.** Capped at 2048
characters and marked `(truncated)` before the log field or the
`Location` header is written. Entries read `field: reason` joined with
`; `, not the parser's debug shape, whose details contain commas and
cannot be split apart again.
- **A repeated `state` is charged to the client, not the callback.**
Reading `state` shares a function with the `redirect_uri` match, so it
used to fall into that carve-out and answer on Coder.

**Where in the OAuth Flow**

<details>
<summary>Diagram: the three-way dispatch, and what licenses a
redirect</summary>

```mermaid
flowchart TD
    NEW["newAuthorizeResponse<br/>parses the registered callback, checks its scheme,<br/>exact-matches any redirect_uri, reads state"]

    NEW -->|"registration unusable"| C500["500 on Coder<br/>server_error, value logged not echoed"]
    NEW --> PARSE["extractAuthorizeParams<br/>reads every parameter, collects all failures"]

    PARSE -->|"no failure"| OK["GET: consent page<br/>POST: authorization code"]
    PARSE -->|"failure"| KIND{"authorizeFailure.kind()"}

    KIND -->|"corrupt registration"| C500
    KIND -->|"redirect_uri or client_id at fault"| CODER["400 on Coder<br/>RFC 6749 4.1.2.1 carve-out"]
    KIND -->|"anything else"| CLIENT["302 to the callback<br/>invalid_request or invalid_target, with state"]
```

</details>

- Authorize endpoint only, both verbs. Token exchange, refresh, and
revocation are untouched, and `ErrorExcessParams` still guards the token
endpoint.
- `validatedCallbackURL` becomes `authorizeResponse`, built only by
`newAuthorizeResponse`, which runs the scheme check and the exact match
in that order. Holding one is what licenses a redirect, so the ordering
is structural rather than a convention each call site remembers.
- The scheme is checked on the *registered* URL, since `p.RedirectURL`
returns the client's URI on a mismatch and checking that would blame the
app for a request it never made.
- `state` moves onto the type, out of the parameter lists of
`withQuery`, `errorURL`, `codeURL`, and `redirectAuthorizeError`, so no
call site can emit a response the client cannot correlate.
- `extractAuthorizeParams` returns one `authorizeFailure` instead of two
trailing values, and both handlers dispatch on `kind()` rather than
re-deriving precedence from field checks.

**What it satisfies**

- RFC 6749 §4.1.2.1: a failure that is not a bad redirection URI or
client identifier is reported through the redirection URI. That is the
whole PR. Its two exceptions "MUST NOT" be redirected to, hence the
carve-outs.
- RFC 6749 §3.1: unrecognized parameters MUST be ignored, and no
parameter may appear more than once. Both now hold here.
- RFC 6749 Appendix A: `error_description` is confined to the permitted
set, on the decoded value.
- RFC 8707 §2: a `resource` that is not an absolute URI without a
fragment answers `invalid_target`.
- RFC 7636 §4.4.1: a malformed `code_challenge` is rejected at the
authorization request rather than deferred to token exchange, where the
error would point at the `code_verifier`.
- Not yet: CRF-26 (the `server_error` sites) and CRF-13 (fragment
delivery), both as in #28450.

**Docs and Swagger.** `docs/admin/integrations/oauth2-provider.md` gains
entries for the redirected parameter errors, `invalid_target`, and the
two failures that stay on Coder. Both authorize verbs document their 400
and 500 responses and stop advertising `response_type=token`, which
meant declaring the parameter as a `string`, since `Enums` appends to
what swaggo derives from the type.

---

Split out of #28045
([PLAT-479](https://linear.app/codercom/issue/PLAT-479)). Fifth of the
stack, stacked on #28450.
## Manual Tests

Verified by hand against a local dev deployment
(`v2.37.0-devel+1145d35a47`, dev Postgres), in addition to the automated
suite. The build string was checked first, because `develop.sh` builds
from whatever the tree held when it started and every result below would
otherwise be describing the wrong binary.

Two scenario groups need state the API cannot produce. The scope
allowlist is reachable only through dynamic client registration, which
was enabled for the run and disabled again at the end. A registered
callback that does not parse, or that uses a blocked scheme, is refused
at registration, so those rows were planted directly with `psql` on a
purpose-built client and restored afterwards.

**28 scenarios, all passing.** No correctness or security defect was
found in the
code this PR changes. Seven observations came out of the run: six are
consistency,
documentation or diagnosability points, and one is a small defect that
predates
this PR.

<details>
<summary><b>Scenario summary, all 28</b></summary>

| # | Scenario | Result |
|---|----------|--------|
| 1 | A well-formed request still succeeds on both verbs, and the
consent page renders | Pass |
| 2 | A rejected parameter now reaches the client's callback on `POST` |
Pass |
| 3 | The same on `GET`, and the consent page does not render first |
Pass |
| 4 | The description names every failing field, joined with `; ` | Pass
|
| 5 | A mismatched `redirect_uri` is answered on Coder with no
`Location` on either verb | Pass |
| 6 | An unparseable `redirect_uri` likewise, and the echoed value is
HTML escaped | Pass |
| 7 | A repeated `client_id` is answered on Coder although the callback
was valid | Pass |
| 8 | A single query `client_id` cannot disagree with the resolved app
over HTTP | Pass |
| 9 | A `client_id` supplied only in the `POST` form body is delivered,
not withheld | Pass |
| 10 | A `{UPPERCASE}` `client_id` is delivered, and also succeeds end
to end | Pass |
| 11 | A repeated `state` is delivered rather than charged to the
redirect carve-out | Pass |
| 12 | A registered callback with a blocked scheme answers 500 on both
verbs | Pass |
| 13 | An unparseable registered callback answers 500, indistinguishably
to the caller | Pass |
| 14 | Corrupt registration outranks a deliverable failure and both
carve-outs | Pass |
| 15 | The corrupt value is logged with the app ID and never appears in
a response | Pass |
| 16 | Restoring the row restores normal behaviour with no restart |
Pass |
| 17 | Every unsupported `response_type` gets one code; an empty one is
`invalid_request` | Pass |
| 18 | An unsupported `response_type` is not recast as a missing
`code_challenge` | Pass |
| 19 | Unrecognized parameters are ignored, including a case-variant
`REDIRECT_URI` | Pass |
| 20 | A misspelled `redirect_url` is ignored and cannot smuggle a
destination | Pass |
| 21 | Repeated known parameters are still rejected | Pass |
| 22 | `resource` answers `invalid_target` alone and `invalid_request`
in company | Pass |
| 23 | A fragment in `resource` is rejected | Pass, with one gap |
| 24 | A long description is capped at 2048 and marked `(truncated)`, on
both verbs | Pass |
| 25 | The description is sanitized to the RFC 6749 §4.1.2.1 character
set | Pass |
| 26 | The registered callback query is retained except the reserved
names | Pass |
| 27 | Scope rejections still reach the callback, and no consent page
renders | Pass |
| 28 | Declining consent carries `access_denied` and issues no code |
Pass |

</details>

<details>
<summary><b>Observations, all 7</b></summary>

| # | Observation | Severity |
|---|-------------|----------|
| 1 | `invalid_request` is returned in three description shapes: the
parser's `Invalid query params: field: reason; ...` aggregate, the PKCE
validator's single message, and `scopeFailureResponse`'s. A client
cannot parse all three with one rule. | Consistency, reviewer call |
| 2 | The phase 2 runbook for #28045 asserts the old `field: x detail:
y` message shape, which this PR replaces. That doc needs a one-line
update. | Docs follow-up |
| 3 | `clientIDInDoubt`'s `default` branch is unreachable over HTTP,
because `httpmw` derives `app.ID` from the same query value the parser
reads. Defensive rather than dead, but the comment does not say so. |
Comment clarity |
| 4 | A `POST` supplying `client_id` only in the form body always fails
with `client_id ... is required and cannot be empty`, naming a parameter
it did supply. `httpmw` reads the body, `RequiredNotEmpty` reads the
query. Pre-existing. | Misleading diagnostic |
| 5 | A misspelled parameter is invisible from every angle at default
verbosity. The client gets a 302 with a code, its redirect is silently
replaced by the registered one, and the `ignoring unrecognized
authorization parameters` line is `logger.Debug` so it is not emitted. |
Diagnosability |
| 6 | `resource` sent twice answers `invalid_target` rather than
`invalid_request`. RFC 8707 §2 frames `invalid_target` as being about
the resource value; a duplicated parameter is a malformed request under
RFC 6749 §3.1. | Low, error code choice |
| 7 | `resource=https://api.example.com/#` (trailing `#`, empty
fragment) is accepted and stored with the `#` intact, so the persisted
audience is not textually equal to the fragment-free form. `url.Parse`
maps empty and absent fragments both to `Fragment == ""`. Pre-existing,
in `tokens.go`. | Defect, low severity |

</details>

**One note for anyone re-running this.** Every request below depends on
`$CHALLENGE` from the most recent `new_pkce` call. Forgetting to call it
sends an empty `code_challenge`, which fails with the fixed "is required
and cannot be empty" message at 98 characters and looks exactly like a
cap or a validator failing to fire. That cost one wrong measurement
during this run before the numbers below were taken.

<details>
<summary><b>Shell helpers used throughout</b></summary>

```bash
export BASE_URL=http://localhost:3000
export AUTH_HEADER="Coder-Session-Token: $(cat ./.coderv2/session)"
export PGPASSWORD=$(cat ./.coderv2/postgres/password)
export PGPORT=$(cat ./.coderv2/postgres/port)

pg() { psql -h localhost -p "$PGPORT" -U coder -d coder -tAc "$1"; }
plant_callback() { pg "UPDATE oauth2_provider_apps SET callback_url = '$2' WHERE id = '$1';"; }
urlenc() { jq -rn --arg v "$1" '$v|@uri'; }

# 43 unreserved characters every time. Base64url of the raw 32 bytes.
new_pkce() {
  VERIFIER=$(openssl rand 32 | base64 | tr -d '\n=' | tr '+/' '-_')
  CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | base64 | tr -d "=" | tr '+/' '-_')
  STATE=$(openssl rand -hex 16)
}

authz_url() {
  local url="$BASE_URL/oauth2/authorize?client_id=$1&response_type=code"
  url="$url&redirect_uri=$(urlenc "$2")&state=$STATE"
  url="$url&code_challenge=$CHALLENGE&code_challenge_method=S256"
  printf '%s' "$url"
}

# The core assertion of the whole run: what answer, delivered where.
answer() { curl -s -o /dev/null -D - -X "$1" "$2" -H "$AUTH_HEADER" | grep -iE '^HTTP/|^location:'; }

show_callback() {
  python3 - "$1" <<'PY'
import sys, urllib.parse
q = urllib.parse.urlparse(sys.argv[1]).query
for k, v in urllib.parse.parse_qsl(q, keep_blank_values=True):
    print(f"{k} = {v}")
PY
}
```

Fixtures, all registered through DCR:

```text
plat479-plain    http://localhost:9876/callback
plat479-query    http://localhost:9876/callback?tenant=acme&error=stale
plat479-corrupt  http://localhost:9876/callback   (overwritten by psql in 12 to 16)
plat479-reserved http://localhost:9876/callback?tenant=acme&code=FAKECODE&error=stale&error_description=oldmsg&state=oldstate&keep=yes
plat479-ci       http://localhost:9876/callback   (scope allowlist coder:workspaces.access)
```

</details>

<details>
<summary><b>1. Baseline: a well-formed request still
succeeds</b></summary>

```bash
new_pkce; answer GET  "$(authz_url "$APP_ID" http://localhost:9876/callback)"
new_pkce; answer POST "$(authz_url "$APP_ID" http://localhost:9876/callback)"
```

```text
=== GET ===
HTTP/1.1 200 OK

=== POST ===
HTTP/1.1 302 Found
Location: http://localhost:9876/callback?code=coder_dzvaCPf9W1_...&state=e321bd5d5b594a1fae8a2d5da654b84a
```

`GET` carries no `Location` at all, so the consent page really rendered
rather than redirecting. The `state` echoed is the one sent. The code
persisted as `coder:all`, this app having no allowlist, with
`redirect_uri` recorded because the request supplied one.

Also driven through a real browser rather than curl, so the consent
form's `nosurf` token is the one submitted rather than the session-token
header alone. Clicking **Allow** delivered `code` and `state` to the
callback. Both request shapes agree on the success case.

Not to be misread: `oauth2_provider_app_codes` holds one row after both
POSTs, not two. `ProcessAuthorize` opens its transaction with
`DeleteOAuth2ProviderAppCodesByAppAndUserID`, so a row count is not a
count of successful authorizations. That predates this PR.

</details>

<details>
<summary><b>2 to 4. A rejected parameter now reaches the client's
callback</b></summary>

```bash
new_pkce
BAD="$BASE_URL/oauth2/authorize?client_id=$APP_ID&response_type=code"
BAD="$BAD&redirect_uri=$(urlenc http://localhost:9876/callback)&state=$STATE"
BAD="$BAD&code_challenge=short&code_challenge_method=S256"
answer POST "$BAD"
answer GET  "$BAD"
```

```text
HTTP/1.1 302 Found
Location: http://localhost:9876/callback?error=invalid_request&error_description=Invalid+query+params%3A+code_challenge%3A+must+be+43+to+128+characters+from+the+unreserved+character+set+%5BA-Za-z0-9-._~%5D&state=e89f4d98d4c8c347e5ae25175748b731
```

Identical on both verbs. Decoded:

```text
error = invalid_request
error_description = Invalid query params: code_challenge: must be 43 to 128 characters from the unreserved character set [A-Za-z0-9-._~]
state = e89f4d98d4c8c347e5ae25175748b731
```

The `GET` body confirms no page was rendered, against the baseline:

| Request | Body size | Occurrences of "Allow" |
|---|---|---|
| Malformed `code_challenge` | 263 bytes | 0 |
| Well formed (scenario 1) | 4928 bytes | 2 |

263 bytes is Go's redirect stub. There is no consent form in it, so
there is no Allow button to press for a request the server has already
refused.

Multiple failures are reported together (scenario 4):

```text
error_description = Invalid query params: code_challenge: must be 43 to 128 characters from the unreserved character set [A-Za-z0-9-._~]; resource: must be an absolute URI without fragment
```

The separator is `; `, and no entry uses the older `field: x detail: y`
shape. The code is `invalid_request` rather than `invalid_target` even
though `resource` is one of the two failures, which is the scenario 22
guard firing.

The same request also carried `code_challenge_method=plain`, which is
invalid and is *not* mentioned, because the method is validated after
`extractAuthorizeParams` returns and a parse failure short-circuits
first. Sent alone it is rejected as `code_challenge_method 'plain' is
not supported; use 'S256'`, with no `Invalid query params: ` prefix.
That difference is observation 1.

</details>

<details>
<summary><b>5 and 6. The redirect_uri carve-out keeps the answer
here</b></summary>

```bash
new_pkce
EVIL="$BASE_URL/oauth2/authorize?client_id=$APP_ID&response_type=code"
EVIL="$EVIL&redirect_uri=$(urlenc http://evil.example/steal)&state=$STATE"
EVIL="$EVIL&code_challenge=$CHALLENGE&code_challenge_method=S256"
answer POST "$EVIL"; answer GET "$EVIL"
```

```text
HTTP/1.1 400 Bad Request
HTTP/1.1 400 Bad Request
```

**The absence in that output is the assertion**: no `Location` on either
verb, so nothing redirects to `evil.example`. Stronger, `evil.example`
appears zero times in either full response, headers and body together,
so the attacker-supplied host is not reflected into the page either.

```json
{"error":"invalid_request","error_description":"Invalid query params: redirect_uri: Query param \"redirect_uri\" must exactly match http://localhost:9876/callback"}
```

The `GET` page names the *registered* callback as the value the
parameter had to match, which is the app's own configuration and safe to
display.

An unparseable `redirect_uri` reaches the same outcome by a different
route, having never parsed at all:

```json
{"error":"invalid_request","error_description":"Invalid query params: redirect_uri: Query param \"redirect_uri\" must be a valid url: parse \"http://%zz\": invalid URL escape \"%zz\""}
```

That message echoes the caller's value, unlike the mismatch case, so the
`GET` path was probed with markup in it:

```text
input:  http://%zz"><img src=x onerror=BAD>
page:   ...must be a valid url: parse &#34;http://%zz\&#34;&gt;&lt;img src=x onerror=BAD&gt;&#34;...
literal `<img` in body: 0     entity encoded `&lt;img`: 1
```

Escaped correctly by the template layer. Recorded as a negative result
so a future change to the error page has something to regress against.

One note for the docs: this detail contains colons, so a client
splitting `field: reason` entries must split each on its **first** colon
only.

</details>

<details>
<summary><b>7 to 10. The client_id carve-out, and its
negatives</b></summary>

A repeated `client_id` in an otherwise perfect request:

```text
HTTP/1.1 400 Bad Request   (both verbs, no Location)
{"error":"invalid_request","error_description":"Invalid query params: client_id: Query param \"client_id\" provided more than once, found 2 times. Only provide 1 instance of this query param."}
```

This is the one carve-out not implied by the response's shape. The
`redirect_uri` matched the registration, so `canRedirect()` was true and
there *was* somewhere to send the answer; it was withheld because
`extractAuthorizeParams` assigns `failure.redirect` only when
`clientIDInDoubt` is false.

**The `default` branch of that function is unreachable over HTTP**
(observation 3). `httpmw` resolves the app from
`r.URL.Query().Get("client_id")`, so `app.ID` and the parsed value
derive from the same string and cannot disagree. Three experiments:

```text
one query client_id, bad challenge          -> 302 delivered
two DIFFERENT client_id values              -> 400, caught by the repeated branch
query names app A, form body names app B    -> 302 to app A; the body is ignored
```

The negatives matter as much as the positives. An identifier absent from
the query but present in the `POST` form body is **delivered**,
correctly:

```text
HTTP/1.1 302 Found
Location: ...error=invalid_request&error_description=Invalid+query+params%3A+client_id%3A+...is+required+and+cannot+be+empty%3B+code_challenge%3A+...
```

That is observation 4: the description says `client_id` is required for
a request that supplied it. With everything else valid the same shape
still fails, while the identical request carrying `client_id` in the
query succeeds with a code. `RequiredNotEmpty` reads the query; `httpmw`
reads the body. Pre-existing, and arguably the parser is the layer in
the right, since RFC 6749 §4.1.1 puts authorization parameters in the
query string and §3.2.1 is the endpoint that uses a form body.

A braced upper-case UUID is delivered, and succeeds end to end:

```text
{UPPERCASE} client_id, bad challenge -> 302, description names ONLY code_challenge
{UPPERCASE} client_id, all valid     -> 302 with a real code
GET, all valid                       -> 200, consent page, heading resolves to the app's real name
```

`uuid.Parse` accepts that spelling and `httpmw` resolved through it, so
a string comparison here would withhold an answer the client is entitled
to, for no reason it could diagnose.

</details>

<details>
<summary><b>11. A repeated state is delivered, not
withheld</b></summary>

```text
HTTP/1.1 302 Found   (both verbs)
error = invalid_request
error_description = Invalid query params: state: Query param 'state' provided more than once, found 2 times. Only provide 1 instance of this query param.
```

Reading `state` happens inside `newAuthorizeResponse`, the same function
that runs the `redirect_uri` match. A count of errors across those two
lines would charge this to the redirect carve-out and answer 400. It
answered 302, so the field-specific test is doing the work.

The asymmetry with scenario 7 is deliberate: a repeated `client_id`
leaves the server unsure whose callback it holds, a repeated `state`
leaves the callback fully settled.

The response carries **no `state`**, since `parseSingle` collapsed the
repeat to the empty string and `withQuery` only sets it when non-empty.
Unavoidable rather than wrong: picking one of two values could satisfy a
CSRF check the client meant to be strict.

</details>

<details>
<summary><b>12 to 16. A corrupt registration outranks
everything</b></summary>

DCR refuses both planted values, which is why `psql` is needed and why
500 is the right answer: a stored one is not something a client did.

```json
{"error":"invalid_client_metadata","error_description":"invalid redirect_uris: redirect URI at index 0: redirect URI uses dangerous scheme javascript which is not allowed"}
{"error":"invalid_client_metadata","error_description":"invalid redirect_uris: redirect URI at index 0 is not a valid URL: parse \"http://%zz\": invalid URL escape \"%zz\""}
```

```bash
plant_callback "$APP_CORRUPT_ID" 'javascript:alert(1)'
new_pkce
CORRUPT="$BASE_URL/oauth2/authorize?client_id=$APP_CORRUPT_ID&response_type=code&state=$STATE"
CORRUPT="$CORRUPT&code_challenge=$CHALLENGE&code_challenge_method=S256"
answer POST "$CORRUPT"; answer GET "$CORRUPT"
```

```text
HTTP/1.1 500 Internal Server Error
{"error":"server_error","error_description":"The application's registered callback URL is not usable"}
GET: HTTP/1.1 500, page reads "500 - Invalid Callback URL", 3346 bytes, 0 Allow buttons
```

The unparseable callback is **indistinguishable to the caller**: same
description, and a `GET` page of exactly 3346 bytes, matching byte for
byte. Two different defects in stored state, one answer. Correct, since
neither is actionable by the client.

Note the request carried no `redirect_uri` of its own and still failed,
because the scheme is checked on the *registered* URL before the
client's value is consulted.

Precedence was tested against all three competitors, not one:

| Also wrong in the request | Would answer alone | Actually answered |
|---|---|---|
| `code_challenge=short` | 302 to the callback | **500** |
| `client_id` repeated | 400 kept here | **500** |
| `redirect_uri` mismatched | 400 kept here | **500** |

Reading the source, this is stronger than precedence.
`newAuthorizeResponse` runs at `authorize.go:250`, before any of
`client_id`, `code_challenge`, `scope` or `resource` is read, and the
early return discards whatever `p.Errors` already held. In rows two and
three those failures are never detected at all, so `kind()` ranking
`failureCorruptRegistration` first is belt and braces for a failure
constructed some other way.

**The value is logged and never echoed.** A distinctive marker was
planted and five requests fired:

```text
[erro] coderd: oauth2 app has an unusable registered callback URL
  request_id=01ca4796-c743-4923-a06b-afc1f3decc95
  app_id=12f9ca3b-7a2c-4c54-8ed7-723698c62bd1
  callback_url="javascript:alert(\"plat479-6d-marker\")"
  error= redirect URI uses dangerous scheme javascript which is not allowed:
         codersdk/oauth2_validation.go:116
```

Five requests, five lines, in request order. Occurrences of the marker
in the POST body, the rendered GET page, and the response headers: **0,
0, 0**.

The `request_id` joins that line to the request log entry whose
`response_body` field holds the vague message, so the server's own
record confirms what it sent for the same request rather than a replay.
The log is also where the two causes diverge, naming `validateScheme`
and its source line, which the response cannot do.

Restoring the row restores normal behaviour immediately, with no
restart:

```text
POST -> 302 with a code      GET -> 200 consent page
```

That is a control rather than housekeeping: it rules out the app having
been poisoned lastingly, and rules out a cached parse outliving the
`UPDATE`.

</details>

<details>
<summary><b>17 and 18. Every unsupported response_type gets one
code</b></summary>

| `response_type` sent | `error` | `error_description` |
|---|---|---|
| `token` | `unsupported_response_type` | Only response_type=code is
supported |
| `banana` | `unsupported_response_type` | Only response_type=code is
supported |
| `code token` | `unsupported_response_type` | Only response_type=code
is supported |
| `CODE` | `unsupported_response_type` | Only response_type=code is
supported |
| `code_extra` | `unsupported_response_type` | Only response_type=code
is supported |
| empty string | `invalid_request` | Invalid query params:
response_type: Query param 'response_type' is required and cannot be
empty |

`token` has a Go constant behind it and `banana` does not, so their
agreement is what reading the value as text bought. Three rows are more
interesting than `banana`: `code token` is a legal RFC 6749 §3.1.1
space-delimited list used by OIDC's hybrid flow, `CODE` confirms the
comparison is case sensitive, and `code_extra` confirms it is equality
rather than a prefix match.

The empty string is correctly the exception. A valueless parameter is
*missing*, not unsupported, and RFC 6749 §3.1 requires it be treated as
omitted.

**The error is in the query, not the fragment.** `response_type=token`
is the implicit grant's own value, so a fragment would be arguable, but
this deployment advertises `"response_types_supported":["code"]` alone,
and a fragment is never sent to the server, so it would be unreadable to
the client's backend.

PKCE is not recast, which the controls show:

| `response_type`, no `code_challenge` sent | `error` |
|---|---|
| `token` | `unsupported_response_type`, zero mentions of
`code_challenge` |
| `banana` | `unsupported_response_type`, zero mentions of
`code_challenge` |
| `code` | `invalid_request`, naming `code_challenge` |

Without the `if params.responseType == responseTypeCode` guard, a client
sending `token` would be told its `code_challenge` was missing, add one,
resend, and be told the same thing again.

</details>

<details>
<summary><b>19 to 21. Unrecognized parameters ignored, repeats still
rejected</b></summary>

Eight unknown parameters, each on an otherwise valid request, every one
issuing a code:

| Unknown parameter | Result |
|---|---|
| `nonce`, `prompt`, `login_hint`, `acr_values`, `max_age`, `ui_locales`
| code issued |
| `code_challenge_methods=S256` | code issued |
| `REDIRECT_URI=http://evil.example/steal` | code issued, **to the
registered callback** |

Five of those are OpenID Connect Core parameters, so an OIDC client
pointed here degrades to plain OAuth2 rather than failing. The ignored
parameters are **dropped, not forwarded**: the callback receives only
`code` and `state`.

The last two rows are the ones with teeth. Query parameter names are
case sensitive, so `REDIRECT_URI` must be ignored, and a misspelled
`redirect_url` likewise:

```text
case variant alongside a valid redirect_uri : Location host localhost:9876
case variant as the only redirect parameter : Location host localhost:9876
redirect_url typo, no valid redirect_uri    : Location host localhost:9876, code issued
evil.example occurrences in any Location    : 0
```

The consent page renders for the typo case too, and even its cancel link
targets the registered callback. A parser matching names
case-insensitively would have redirected to `evil.example` with a valid
code attached.

**Observation 5.** The `ignoring unrecognized authorization parameters`
line was never emitted. Three requests carrying a distinctive marker
produced no new server output at all, because the call is `logger.Debug`
(`authorize.go:307`) and the deployment runs with `verbose: null`. The
behaviour is correct and required by RFC 6749 §3.1, but at default
verbosity the misspelling is invisible from every angle: the client sees
a 302 with a code, its redirect is silently replaced, and nothing is
logged. The comment claiming the typo "surfaces here" is optimistic.

Repeats of known parameters are still rejected, which the replacement of
`ErrorExcessParams` had to leave alone:

| Repeated parameter | HTTP | `error` | Answered at |
|---|---|---|---|
| `code_challenge` | 302 | `invalid_request`, two entries one field |
client callback |
| `code_challenge_method` | 302 | `invalid_request` | client callback |
| `response_type` | 302 | `invalid_request` | client callback |
| `redirect_uri` | 400 | withheld | **Coder** |
| `scope` | 302 | `invalid_request` | client callback |
| `resource` | 302 | `invalid_target` | client callback |

`redirect_uri` being withheld confirms the carve-out keys on the field
name rather than the kind of mistake. `code_challenge` collects two
entries for one mistake, because `parseSingle` collapses the value to
empty and the PKCE block then reports it missing. The `resource` row is
observation 6.

</details>

<details>
<summary><b>22 and 23. resource, its own code, and the fragment
rule</b></summary>

Both sides of the rule, since a check enforced too broadly would reject
a valid URN:

| `resource` sent | `error` | Stored `resource_uri` |
|---|---|---|
| `not a uri` | `invalid_target` | not stored |
| `/api` relative | `invalid_target` | not stored |
| `https://api.example.com` | none, code issued | as sent |
| `https://api.example.com/v1?q=1` | none, code issued | as sent, query
is not a fragment |
| `urn:example:resource` | none, code issued | as sent |
| empty string | none, code issued | `NULL`, same as omitted |

`invalid_target` applies only when `resource` is the sole failure. Add
any second failure in any other field and the code becomes
`invalid_request` naming both, which is the retry-loop guard:

```text
resource + bad code_challenge -> invalid_request, both named
resource + repeated scope     -> invalid_request, both named
resource + repeated state     -> invalid_request, both named
resource alone (control)      -> invalid_target
```

Fragments are rejected in all three placements, with or without a path:

```text
https://api.example.com/#x         -> invalid_target
https://api.example.com#x          -> invalid_target
https://api.example.com/v1#frag    -> invalid_target
https://api.example.com/#          -> code issued, stored as https://api.example.com/#
```

**The last row is observation 7, and it predates this PR.** Go cannot
represent the distinction:

```text
https://a.example.com/    Fragment=""  String()="https://a.example.com/"
https://a.example.com/#   Fragment=""  String()="https://a.example.com/"
https://a.example.com/#x  Fragment="x" String()="https://a.example.com/#x"
```

`url.Parse` collapses "no fragment" and "empty fragment", so `if
u.Fragment != ""` in `validateResourceParameter`
(`coderd/oauth2provider/tokens.go:591`) cannot see a trailing `#`. RFC
3986 §3.5 permits a zero-length fragment, which RFC 8707 §2's "MUST NOT
include a fragment component" reads as forbidding. Validation parses the
value but persistence stores the raw string, so the `#` reaches
`resource_uri` and the stored audience is not textually equal to the
fragment-free form. A client appending a harmless-looking `#` would get
a token bound to an audience nothing matches.

The authorize-side call to `validateResourceParameter` is context in
this diff rather than an added line; this PR added the `invalid_target`
code for the failure.

</details>

<details>
<summary><b>24 and 25. The description cap and character
set</b></summary>

The obvious probe does not exercise the cap: a 4000-character
`code_challenge` produces a 116-character description, because that
message is fixed text and never quotes the offending value. The
descriptions that echo caller input come from a validator's own error.

| Request | `error` | Description length | Truncated | `Location` length
|
|---|---|---|---|---|
| `code_challenge_method` = 4000 chars | `invalid_request` | 2060 |
**yes** | 2176 |
| `scope` = 4000 chars | `invalid_scope` | 2060 | **yes** | 2174 |
| `code_challenge_method` = 2000 chars | `invalid_request` | 2035 | no |
2147 |
| `code_challenge` = 4000 chars | `invalid_request` | 116 | no | 234 |

2060 is exactly `maxErrorDescription` plus `" (truncated)"`. Row three
is the boundary control, so the cap fires on length rather than on the
presence of echoed input. Measured from the `Location` header rather
than a log line, since the stated reason for the cap is that the header
must survive intermediary proxies; the longest observed was 2176 bytes.

Both verbs agree, the cap living in the shared `redirectAuthorizeError`:

```text
GET, long method : desc_len=2060 truncated=True
GET, long scope  : desc_len=2060 truncated=True
```

The character set is enforced independently, later, in `errorURL`:

```text
input:       pl"ain\back<newline>tab<tab>end~unicode
description: unsupported code_challenge_method: pl'ainback tab end~ nicode
chars outside the RFC 6749 §4.1.2.1 set: []
```

`"` becomes `'`, `\` is dropped so it cannot escape the rewritten quote,
and anything below 0x20 or above 0x7E becomes a space. Checked
programmatically rather than by eye. The RFC sets no length limit, so
the 2048 cap is policy; the character set is conformance.

</details>

<details>
<summary><b>26. The registered callback query, retained except reserved
names</b></summary>

`plat479-reserved` registers a callback carrying all four reserved names
plus two ordinary ones, and DCR stores it unchanged:

```text
http://localhost:9876/callback?tenant=acme&code=FAKECODE&error=stale&error_description=oldmsg&state=oldstate&keep=yes
```

Success response, no `redirect_uri` sent:

```text
code  = coder_WXwBpvYR5u_...
keep  = yes
state = 516abeea9976119eb33ddc10f0ca04ed
tenant = acme
```

Failure response, same app:

```text
error = invalid_request
error_description = Invalid query params: code_challenge: must be 43 to 128 characters...
keep  = yes
state = 3a17bdd75dfcf740bda36124cd161fb7
tenant = acme
```

Stale registered values in either response: `FAKECODE` 0, `stale` 0,
`oldmsg` 0, `oldstate` 0.

Without the deletion step a registered `error=stale` would ride out on
the **success** response, and a client reading `error` before `code`,
the conventional order, would discard a valid authorization code.
`FAKECODE` is the mirror image on a failure response.

The cancel link obeys the same rule, being built by the same `withQuery`
path:

```text
http://localhost:9876/callback?error=access_denied&error_description=The+resource+owner...&keep=yes&state=e15b5f0f...&tenant=acme
```

RFC 6749 §3.1.2 requires the registered query be retained when adding
parameters, which is the `tenant` and `keep` half. It does not say what
to do when the registered query collides with the response parameters
§4.1.2 adds, so dropping the registered copies is the resolution that
keeps the client's read unambiguous.

</details>

<details>
<summary><b>27 and 28. Scope rejections, and declining
consent</b></summary>

`plat479-ci` carries the allowlist `coder:workspaces.access`.

```text
scope=template:update (outside)  -> error = invalid_scope
                                    'template:update': scope requests permissions beyond this app's allowed scopes
GET, same request                -> 302, 225 bytes, 0 Allow buttons, no consent page
scope=workspace:ssh (covered)    -> code issued, persisted scope workspace:ssh
GET, same request                -> 200, 5182 bytes, consent page naming the scope
```

`workspace:ssh` is granted although the allowlist names the composite
rather than that scope, which is the coverage-not-spelling rule from
#28045. This run only checks that the changes here left it delivering
the same answers.

The consent page for a narrow scope reads differently from the
unrestricted one: "to access your **admin** account with these
permissions?", the scope as `<li role="listitem">workspace:ssh`, and the
caution "These are technical permission names. Grant them only to an
application you trust."

The scope description shape differs from the parser's, coming from
`scopeFailureResponse` rather than the field join, which is the third
producer behind observation 1.

Declining consent, clicked in a real browser:

```text
error             = access_denied
error_description = The resource owner or authorization server denied the request
state             = a8bd538b365b61f54586892c73968b80
```

The page carries exactly one `href` and it is the cancel link. The
`state` matches, there is no `code`, and the code count for the app is
unchanged, the link being a plain `GET` to the client's callback that
never reaches `ProcessAuthorize`. The description is RFC 6749 §4.1.2.1's
own definition of `access_denied`, word for word.

That shared construction is what makes the `#nosec G203` annotation on
`CancelURI` sound: the URL is injected as a trusted `htmltemplate.URL`,
safe only because `newAuthorizeResponse` validated the registered scheme
before the response object could exist. Scenario 12 is the other half,
an app with a rejected scheme never reaching this page at all.

</details>

<details>
<summary><b>Where the consent page renders, across every GET
case</b></summary>

Only `GET` can render anything, and body size identifies which of four
renderers ran, so this is the table to check when a status code alone
looks right.

| Case | Status | Body bytes | Allow buttons | Rendered |
|---|---|---|---|---|
| well formed | 200 | 4928 | 1 | **consent page** |
| bad `code_challenge` | 302 | 263 | 0 | redirect stub |
| two bad fields | 302 | 319 | 0 | redirect stub |
| mismatched `redirect_uri` | 400 | 3814 | 0 | 400 error page |
| unparseable `redirect_uri` | 400 | 3846 | 0 | 400 error page |
| repeated `client_id` | 400 | 3846 | 0 | 400 error page |
| `client_id` in form body only | 400 | 77 | 0 | `httpmw` JSON, unstyled
|
| `{UPPERCASE}` `client_id` | 200 | 4940 | 1 | **consent page** |
| repeated `state` | 302 | 239 | 0 | redirect stub |
| corrupt callback, blocked scheme | 500 | 3346 | 0 | 500 error page |
| corrupt callback, unparseable | 500 | 3346 | 0 | 500 error page |
| `response_type=token` | 302 | 187 | 0 | redirect stub |
| `banana` / `code token` / `CODE` | 302 | 187 | 0 | redirect stub |
| empty `response_type` | 302 | 243 | 0 | redirect stub |
| `token`, no PKCE | 302 | 187 | 0 | redirect stub |
| `code`, no PKCE | 302 | 245 | 0 | redirect stub |
| unknown params, valid request | 200 | 4932 | 1 | **consent page** |
| `redirect_url` typo, valid request | 200 | 4932 | 1 | **consent page**
|
| `resource` malformed | 302 | 214 | 0 | redirect stub |
| `resource` valid absolute URI | 200 | 4932 | 1 | **consent page** |
| `resource=.../#` empty fragment | 200 | 4932 | 1 | **consent page**,
observation 7 |
| reserved params in registered callback | 200 | 4973 | 1 | **consent
page** |
| `scope` outside allowlist | 302 | 225 | 0 | redirect stub |
| `scope` covered by allowlist | 200 | 5182 | 1 | **consent page** |

The invariant: the page renders if and only if `extractAuthorizeParams`
returned no failure, so no input asks the owner to approve a request the
server has already refused. The `evil.example` rows are worth reading
carefully rather than alarming: RFC 6749 §3.1 requires a case variant
and a typo to be ignored, so from the server's view nothing was wrong
with either request, and both cancel links target the registered
callback.

About 4930 bytes is the consent page, about 3800 the 400 page, 3346 the
500 page, 77 the unstyled `httpmw` JSON, and low hundreds is Go's
redirect stub, whose length tracks the `Location` it embeds. Every
`unsupported_response_type` answer is exactly 187 bytes because they
share one description. Small variations within a renderer are expected:
the consent page moves 4928 to 4940 with a fresh CSRF token and the app
name.

As a regression signal, body size is more sensitive than the status
line. A change that rendered a page alongside a redirect would still
report 302, but the stub would come back at thousands of bytes rather
than hundreds.

</details>

<details>
<summary><b>Cleanup</b></summary>

```bash
for id in $(pg "SELECT id FROM oauth2_provider_apps WHERE name LIKE 'plat479%';"); do
  curl -s -X DELETE "$BASE_URL/api/v2/oauth2-provider/apps/$id" -H "$AUTH_HEADER" \
    -o /dev/null -w "$id -> %{http_code}\n"
done
pg "SELECT count(*) FROM oauth2_provider_apps WHERE name LIKE 'plat479%';"
./scripts/coder-dev.sh oauth2-provider dcr disable
```

All planted callback rows were restored before deletion, so no fixture
was left holding a value DCR would refuse.

</details>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Steven Masley <Emyrk@users.noreply.github.com>
2026-09-03 10:54:34 -07:00

223 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",
      "connect_time": "2019-08-24T14:15:22Z",
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "ip": "string",
      "organization": {
        "display_name": "string",
        "icon": "string",
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "name": "string"
      },
      "ssh_info": {
        "connection_id": "d3547de1-d1f2-4344-b4c2-17169b7526f9",
        "disconnect_reason": "string",
        "disconnect_time": "2019-08-24T14:15:22Z",
        "exit_code": 0
      },
      "type": "ssh",
      "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, oidc, password, token
status active, 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",
    "endpoints": {
      "authorization": "string",
      "device_authorization": "string",
      "token": "string",
      "token_revoke": "string"
    },
    "icon": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "name": "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
» 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

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"
}

Parameters

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

Example responses

200 Response

{
  "callback_url": "string",
  "endpoints": {
    "authorization": "string",
    "device_authorization": "string",
    "token": "string",
    "token_revoke": "string"
  },
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "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",
  "endpoints": {
    "authorization": "string",
    "device_authorization": "string",
    "token": "string",
    "token_revoke": "string"
  },
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "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"
}

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",
  "endpoints": {
    "authorization": "string",
    "device_authorization": "string",
    "token": "string",
    "token_revoke": "string"
  },
  "icon": "string",
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "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. 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)

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, oidc, password, token
status active, 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

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

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 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
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 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, oidc, password, token
status active, 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. The app's registered callback URL 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 The app's registered callback URL 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

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

Revoke OAuth2 tokens (RFC 7009)

Code samples

# Example request using curl
curl -X POST http://coder-server:8080/oauth2/revoke \

POST /oauth2/revoke

Body parameter

client_id: string
token: string
token_type_hint: string

Parameters

Name In Type Required Description
body body object true
» client_id body string true Client ID for authentication
» token body string true The token to revoke
» token_type_hint body string false Hint about token type (access_token or refresh_token)

Responses

Status Meaning Description Schema
200 OK Token successfully revoked

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

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.