**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 "http://%zz\"><img src=x onerror=BAD>"... literal `<img` in body: 0 entity encoded `<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>
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.