---
title: "Start RFC 8628 OAuth device authorization for an integration."
method: POST
path: "/v1/integrations/device/start"
tags: ["integrations"]
---

# Start RFC 8628 OAuth device authorization for an integration.

`POST /v1/integrations/device/start`

## Request

- Base URL: `https://api.kody.codes`
- URL: `https://api.kody.codes/v1/integrations/device/start`
- Auth: HTTP bearer

Start RFC 8628 OAuth device authorization for an integration. Returns a user_code and verification URI for the signed-in user to approve at the provider. The provider device_code and any client secret stay server-side and never appear in the output. Poll with integrationDeviceConnectPoll until approved or failed. Prefer /connect/oauth?flow=device for interactive browser flows; use this capability when an agent must drive device connect without a browser redirect.

Org permission: `integration:write`.

## Request body

- object
  - `provider` string, required: Connection / provider name to create or reconnect via device authorization.
  - `platformAppSlug` string: Optional platform (built-in) app slug. When set, endpoints and client id come from the app row.
  - `tokenUrl` string, uri
  - `deviceAuthorizationUrl` string, uri
  - `authorizeUrl` string, uri
  - `apiBaseUrl` string, uri, nullable
  - `clientId` string
  - `clientSecret` string: Optional client secret for confidential device clients. Never returned in outputs.
  - `scopes` string[]
  - `scopeSeparator` string, nullable
  - `extraAuthorizeParams` object
  - `allowedHosts` string[]
  - `tokenExchangeStyle` 'form' | 'basic-json' | 'basic-form'
  - `usePkce` boolean, nullable

## Response `200`

Success.

- object
  - `ok` true, required
  - `sessionId` string, required: Opaque session id for integrationDeviceConnectPoll.
  - `userCode` string, required: Code the user enters at the provider.
  - `verificationUri` string, uri, required
  - `verificationUriComplete` string, uri, nullable, required
  - `expiresIn` integer, required
  - `interval` integer, required

## Other responses

- `400`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `401`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `403`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `404`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `409`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `413`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `429`: Too many requests (edge IP/token limit) or an entitlement / plan-cap limit. Wait at least `Retry-After` seconds before retrying.
- `500`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `503`: Error envelope `{ "error": { "code", "message", "details"? } }`.
- `default`: Error envelope `{ "error": { "code", "message", "details"? } }`.

---

[API](https://skmtc.dev/kody/apis/kody-api.md) · [All operations](https://skmtc.dev/kody/apis/kody-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kody/apis/kody-api/revisions/a020ecedb82b?raw)