API documentation

Build Kick authorization workflows, inspect permissions, and manage tokens with the v2 API.

Authorization workflow

Read the scope catalog and choose the active scope IDs your integration needs.
Create a workflow. Keep its retrieval key private and open authorization_url in the account owner’s browser.
After authorization, retrieve the credentials once. Save both the access token and the latest refresh token.

Workflows expire after 24 hours. A successful retrieval consumes the stored credentials. Wait at least five seconds between pending checks.

Authentication and limits

Workflow retrieval uses its own private key as a Bearer credential. Other endpoints use the inputs shown below. The v2 API allows 120 requests per minute per IP; HTTP 429 means the limit was reached.

Request helper

Example responses run locally. Send live request calls the real API once; it can create links, consume credentials, or revoke a token.

Endpoint

Response example

Replace example values before sending. Entered credentials are kept in this tab and sent only when you choose Send live request. They are not saved in browser storage.

Request preview

Loading API definition…

Response

Endpoint reference

GET /api/v2/scopes

Available Token Scopes

Read current scope IDs, names, descriptions, and availability. This request needs no credentials.

This endpoint has no request parameters.

Response

HTTP 200: Successful response
application/json
Example response
{ "scopes": [ { "description": "Send chat messages as the authorized account.", "id": 6, "scope": "chat:write", "secret": false } ], "success": true }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

POST /api/v2/workflows

Create an authorization workflow

Create a 24-hour authorization workflow. Use shared mode when enabled, or supply your own application credentials in the POST body.

Parameters

ai_agentOptional

string · body

Optional AI client name, up to 64 UTF-8 bytes without control characters. This is attribution, not authentication.

credentialsOptional

object · body

Use your own Kick developer application. Leave both fields empty only when shared mode is available. Credentials remain in memory in this tab and are encrypted temporarily on this server during authorization.

is_aiOptional

boolean · body

Mark a workflow as AI-assisted.

redirect_urlOptional

string · body

Optional absolute HTTPS destination after authorization. No URL credentials or fragments. Tokens are never appended.

scope_idsOptional

array · body

Numeric IDs from the scope catalog. Choose active scopes; at most 150 distinct scopes.

scopesOptional

array · body

Canonical Kick scope names from the catalog; alternatively use scope_ids.

titleOptional

string · body

Application name, up to 500 UTF-8 bytes.

JSON request body

{
  "credentials": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  },
  "scope_ids": [
    6
  ],
  "title": "Example integration"
}

Response

HTTP 201: Created
application/json
Example response
{ "authorization_url": "https://kicktokengen.com/authorize/EXAMPLE_ID", "expires_at": "2030-01-02T12:00:00Z", "id": "EXAMPLE_ID", "retrieval_key": "EXAMPLE_PRIVATE_KEY", "status_url": "https://kicktokengen.com/api/v2/workflows/EXAMPLE_ID", "success": true }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

GET /api/v2/workflows/{id}

Retrieve workflow credentials

Returns credentials once after authorization. Send the workflow retrieval key as a Bearer credential. A successful read consumes the stored credentials.

Parameters

idRequired

string · path

The workflow ID returned when it was created.

AuthorizationRequired

Bearer · header

The private retrieval key returned when the workflow was created. Keep it out of public links.

Response

HTTP 200: Successful response
application/json
Example response
{ "access_token": "EXAMPLE_ACCESS_TOKEN", "client_id": "EXAMPLE_CLIENT_ID", "expires_at": "2030-01-01T13:00:00Z", "expires_in": 3600, "refresh_token": "EXAMPLE_REFRESH_TOKEN", "scopes": [ "chat:write" ], "status": "authorized", "success": true, "token_type": "Bearer" }
HTTP 202: Authorization is still pending
application/json
Example response
{ "status": "pending", "success": false }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 410: Credentials expired or already retrieved
application/json
Example response
{ "message": "workflow credentials are no longer available", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

GET /api/v2/ai/workflows/create

Create a fetch-only AI workflow

Fetch-only alternative using the enabled shared application. Pass scope_ids separated by commas, or space-separated canonical scopes. Returns a public authorization link and a private retrieval URL.

Parameters

titleOptional

string · query

Application name, up to 500 UTF-8 bytes.

scopesOptional

string · query

Canonical Kick scope names from the catalog; alternatively use scope_ids.

scope_idsOptional

string · query

Numeric IDs from the scope catalog. Choose active scopes; at most 150 distinct scopes.

ai_agentOptional

string · query

Optional AI client name, up to 64 UTF-8 bytes without control characters. This is attribution, not authentication.

Response

HTTP 201: Created
application/json
Example response
{ "authorization_url": "https://kicktokengen.com/authorize/EXAMPLE_ID", "id": "EXAMPLE_ID", "retrieval_url": "https://kicktokengen.com/api/v2/ai/workflows/EXAMPLE_ID/EXAMPLE_PRIVATE_KEY", "success": true }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

GET /api/v2/ai/workflows/{id}/{key}

Retrieve fetch-only AI credentials

A private URL containing the retrieval key. The JSON response delivers credentials once; treat the entire URL as a password.

Parameters

idRequired

string · path

The workflow ID returned when it was created.

keyRequired

string · path

The private retrieval key returned when the workflow was created. Keep it out of public links.

Response

HTTP 200: Successful response
application/json
Example response
{ "access_token": "EXAMPLE_ACCESS_TOKEN", "client_id": "EXAMPLE_CLIENT_ID", "expires_at": "2030-01-01T13:00:00Z", "expires_in": 3600, "refresh_token": "EXAMPLE_REFRESH_TOKEN", "scopes": [ "chat:write" ], "status": "authorized", "success": true, "token_type": "Bearer" }
HTTP 202: Authorization is still pending
application/json
Example response
{ "status": "pending", "success": false }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 410: Credentials expired or already retrieved
application/json
Example response
{ "message": "workflow credentials are no longer available", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

POST /api/v2/tokens/validate

Validate Token

Check token validity and report the issuing application, token type, granted permissions and expiry returned by Kick.

Parameters

access_tokenRequired

string · body

The Kick access token to inspect or revoke, without an oauth: prefix.

JSON request body

{
  "access_token": "EXAMPLE_ACCESS_TOKEN"
}

Response

HTTP 200: Successful response
application/json
Example response
{ "active": true, "client_id": "EXAMPLE_CLIENT_ID", "exp": 1893502800, "expires_in": 3600, "scope_details": [ { "description": "Send chat messages.", "scope": "chat:write" } ], "scopes": [ "chat:write" ], "success": true, "token_type": "user" }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid access token", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

POST /api/v2/tokens/refresh

Refresh token

Renews an access token using a refresh token. Supply both client_id and client_secret when refreshing a token from your own Kick application.

Parameters

client_idOptional

string · body

Issuing Kick application client ID. Blank selects shared mode only when enabled.

client_secretOptional

string · body

Issuing application client secret. Required for custom-client refresh; never needed for this site’s enabled shared-app refresh.

refresh_tokenRequired

string · body

The latest refresh token for the account and Kick application.

JSON request body

{
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "refresh_token": "EXAMPLE_REFRESH_TOKEN"
}

Response

HTTP 200: Successful response
application/json
Example response
{ "access_token": "EXAMPLE_ACCESS_TOKEN", "client_id": "EXAMPLE_CLIENT_ID", "expires_at": "2030-01-01T13:00:00Z", "expires_in": 3600, "refresh_token": "EXAMPLE_REFRESH_TOKEN", "scopes": [ "chat:write" ], "status": "authorized", "success": true, "token_type": "Bearer" }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid refresh token or client credentials", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

POST /api/v2/tokens/revoke

Revoke Token

Revoke exactly one access token or refresh token supplied in the POST body.

Parameters

access_tokenOptional

string · body

The Kick access token to inspect or revoke, without an oauth: prefix.

refresh_tokenOptional

string · body

The latest refresh token for the account and Kick application.

JSON request body

{
  "access_token": "EXAMPLE_ACCESS_TOKEN"
}

Response

HTTP 200: Successful response
application/json
Example response
{ "revoked": true, "success": true }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid token request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

POST /api/v2/quick-links

Quick Link

Creates a reusable link with selected scope IDs. auth=stay opens the generator; auth=authorize starts Kick authorization.

Parameters

authOptional

string · body

stay opens the generator. authorize and the compatibility alias auth_auth begin authorization immediately.

scope_idsOptional

array · body

Numeric IDs from the scope catalog. Choose active scopes; at most 150 distinct scopes.

scopesOptional

array · body

Canonical Kick scope names from the catalog; alternatively use scope_ids.

JSON request body

{
  "auth": "stay",
  "scope_ids": [
    6
  ]
}

Response

HTTP 201: Created
application/json
Example response
{ "success": true, "url": "https://kicktokengen.com/quick/Ab3dEf8_" }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint

POST /api/v2/token-requests

Request Token

Creates an authorization request link. After the account owner completes authorization, credentials are sent to my_email.

Parameters

credentialsOptional

object · body

my_emailRequired

string · body

Email address that receives credentials after the request is completed.

my_nameRequired

string · body

Requester name, up to 128 UTF-8 bytes.

scope_idsOptional

array · body

Numeric IDs from the scope catalog. Choose active scopes; at most 150 distinct scopes.

scopesOptional

array · body

Canonical Kick scope names from the catalog; alternatively use scope_ids.

JSON request body

{
  "credentials": {
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  },
  "my_email": "developer@example.com",
  "my_name": "Example developer",
  "scope_ids": [
    6
  ]
}

Response

HTTP 201: Created
application/json
Example response
{ "expires_at": "2030-01-02T12:00:00Z", "success": true, "url": "https://kicktokengen.com/request/EXAMPLE_ID" }
HTTP 400: Invalid request
application/json
Example response
{ "message": "invalid request", "success": false }
HTTP 401: Invalid token or retrieval key
application/json
Example response
{ "message": "invalid retrieval key", "success": false }
HTTP 429: Rate limit reached
application/json
Example response
{ "message": "rate limit exceeded", "success": false }
HTTP 503: Service temporarily unavailable
application/json
Example response
{ "message": "Service unavailable", "success": false }

Try this endpoint