---
title: Start CLI device authorization
description: Creates a short-lived PKCE-bound device authorization request for
  the Inth CLI. This endpoint is only available when CLI device authorization is
  enabled.
type: api-reference
source: ./openapi/inth-api.json
method: post
path: /v1/auth/device/code
operationId: createDeviceAuthorizationRequest
server: https://api.inth.com
apiVersion: 1.0.0
tags:
  - Auth
canonicalUrl: https://inth.com/docs/rest-api/auth/create-device-authorization-request
lastModified: "2026-08-23T09:10:26.417Z"
---
```http
POST /v1/auth/device/code
```

Server: `https://api.inth.com`

Operation ID: `createDeviceAuthorizationRequest`

## Request

### Request Body

required

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`clientId`|string|required||
|`codeChallenge`|string|required||
|`codeChallengeMethod`|string|required||

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "clientId",
    "codeChallenge",
    "codeChallengeMethod"
  ],
  "properties": {
    "clientId": {
      "type": "string",
      "minLength": 1
    },
    "codeChallenge": {
      "type": "string",
      "minLength": 1
    },
    "codeChallengeMethod": {
      "type": "string",
      "const": "S256"
    }
  }
}
```

## Code Examples

### cURL

```bash
curl -X POST "https://api.inth.com/v1/auth/device/code" \
  -H "Content-Type: application/json" \
  -d '{
  "clientId": "string",
  "codeChallenge": "string",
  "codeChallengeMethod": "string"
}'
```

### JavaScript

```ts
const response = await fetch("https://api.inth.com/v1/auth/device/code", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "clientId": "string",
    "codeChallenge": "string",
    "codeChallengeMethod": "string"
  }),
});
const data = await response.json();
```

## Responses

### 201

Device authorization request created.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`data`|object|required||
|`data.deviceCode`|string|required||
|`data.userCode`|string|required||
|`data.client`|object|required||
|`data.client.id`|string|required||
|`data.client.name`|string|required||
|`data.client.publisher`|string|required||
|`data.expiresIn`|integer|required||
|`data.interval`|integer|required||
|`data.verificationUri`|string (uri)|required||
|`data.verificationUriComplete`|string (uri)|required||

Example:

```json
{
  "success": true,
  "data": {
    "deviceCode": "string",
    "userCode": "string",
    "client": {
      "id": "string",
      "name": "string",
      "publisher": "string"
    },
    "expiresIn": 0,
    "interval": 0,
    "verificationUri": "https://example.com",
    "verificationUriComplete": "https://example.com"
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "data"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": true
    },
    "data": {
      "type": "object",
      "required": [
        "deviceCode",
        "userCode",
        "client",
        "expiresIn",
        "interval",
        "verificationUri",
        "verificationUriComplete"
      ],
      "properties": {
        "deviceCode": {
          "type": "string"
        },
        "userCode": {
          "type": "string"
        },
        "client": {
          "type": "object",
          "required": [
            "id",
            "name",
            "publisher"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "publisher": {
              "type": "string"
            }
          }
        },
        "expiresIn": {
          "type": "integer"
        },
        "interval": {
          "type": "integer"
        },
        "verificationUri": {
          "type": "string",
          "format": "uri"
        },
        "verificationUriComplete": {
          "type": "string",
          "format": "uri"
        }
      }
    }
  }
}
```

### 400

The request payload or parameters are invalid.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSTANCE\_LIMIT\_REACHED" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example: default

```json
{
  "success": false,
  "error": {
    "code": "INVALID_PAYLOAD",
    "message": "Invalid request payload",
    "details": [
      {
        "code": "too_small",
        "message": "Too small: expected string to have >=1 characters",
        "path": [
          "name"
        ]
      }
    ]
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSTANCE_LIMIT_REACHED",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 401

Authentication is missing, invalid, or expired.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSTANCE\_LIMIT\_REACHED" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example: default

```json
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSTANCE_LIMIT_REACHED",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 402

The requested operation requires a paid plan. API access (organization API keys) requires the Starter plan or higher; a downgraded organization receives this error until its plan is restored.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSTANCE\_LIMIT\_REACHED" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example: default

```json
{
  "success": false,
  "error": {
    "code": "PLAN_REQUIRED",
    "message": "API access requires the Starter plan or higher"
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSTANCE_LIMIT_REACHED",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 403

The authenticated principal cannot access the resource.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSTANCE\_LIMIT\_REACHED" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example:

```json
{
  "success": true,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "string",
    "details": {}
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSTANCE_LIMIT_REACHED",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 404

The requested resource was not found.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSTANCE\_LIMIT\_REACHED" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example:

```json
{
  "success": true,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "string",
    "details": {}
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSTANCE_LIMIT_REACHED",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 413

The request body exceeds the 1 MB limit.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSTANCE\_LIMIT\_REACHED" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example:

```json
{
  "success": true,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "string",
    "details": {}
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSTANCE_LIMIT_REACHED",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 429

The rate limit was exceeded. API key limits are set by plan tier (Starter 600/min, Pro 1500/min, Enterprise 3000/min). Check the Retry-After header before retrying.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSTANCE\_LIMIT\_REACHED" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example: default

```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "API key rate limit exceeded"
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSTANCE_LIMIT_REACHED",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

### 500

An unexpected internal error occurred.

Content type: application/json

|Property|Type|Required|Description|
|:--|:--|:--|:--|
|`success`|boolean|required||
|`error`|object|required||
|`error.code`|"UNAUTHORIZED" \|"FORBIDDEN" \|"INSTANCE\_LIMIT\_REACHED" \|"PLAN\_LIMIT\_REACHED" \|"PLAN\_REQUIRED" \|"INVALID\_ORIGIN" \|"INVALID\_REGION" \|"INVALID\_PAYLOAD" \|"NOT\_FOUND" \|"CONFLICT" \|"KEY\_LIMIT\_REACHED" \|"PAYLOAD\_TOO\_LARGE" \|"RATE\_LIMITED" \|"SERVICE\_UNAVAILABLE" \|"INTERNAL\_ERROR"|required||
|`error.message`|string|required||
|`error.details`|unknown|optional|Optional structured error details.|

Example: default

```json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}
```

JSON Schema:

```json
{
  "type": "object",
  "required": [
    "success",
    "error"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "const": false
    },
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string",
          "enum": [
            "UNAUTHORIZED",
            "FORBIDDEN",
            "INSTANCE_LIMIT_REACHED",
            "PLAN_LIMIT_REACHED",
            "PLAN_REQUIRED",
            "INVALID_ORIGIN",
            "INVALID_REGION",
            "INVALID_PAYLOAD",
            "NOT_FOUND",
            "CONFLICT",
            "KEY_LIMIT_REACHED",
            "PAYLOAD_TOO_LARGE",
            "RATE_LIMITED",
            "SERVICE_UNAVAILABLE",
            "INTERNAL_ERROR"
          ]
        },
        "message": {
          "type": "string"
        },
        "details": {
          "description": "Optional structured error details."
        }
      }
    }
  }
}
```

## Related

* [REST API overview](/docs/rest-api): Every operation in this API.