---
title: "Authentication — API reference"
description: "Browser sign-in for command-line tools (device authorization, like `gh auth login`) and the session of the key in use. 1) `POST /auth/device/code` (no"
url: https://www.gyrohosting.com/developers/en/api/authentication.html
language: en
openapi: https://www.gyrohosting.com/developers/openapi.json
api_version: 2.31.0
---

# Authentication

Browser sign-in for command-line tools (device authorization, like `gh auth login`) and the session of the key in use. 1) `POST /auth/device/code` (no key) returns a `user_code` and an address; 2) the user opens it, signs in to the panel, checks the code and the request's IP/client, picks permissions and expiry, approves; 3) the tool polls `POST /auth/device/token` every `interval` seconds and receives a new client API key once. The key is an ordinary key: listed and revocable on the API Credentials page, same permission model, money rules and IP lock. In CI keep using a key created on the panel or with `POST /cloud/keys`.

Base URL: `https://www.gyrohosting.com/api/v1/client` · OpenAPI: https://www.gyrohosting.com/developers/openapi.json


## POST /auth/device/code

**Start a browser sign-in (device code)** · operationId `createDeviceCode` · scope `` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/createDeviceCode.json

No API key. Limits: 10 codes per IP per 10 minutes (429 `rate_limited`). The code is valid for `expires_in` seconds. `template` / `scopes` only preselect permissions on the approval page; the user decides.


### Request body

| Field | Type | Description |
|---|---|---|
| `client_name` | string |  |
| `client_version` | string |  |
| `hostname` | string |  |
| `os` | string |  |
| `template` | string (readonly, dns, cloud, containers, storage, billing, full, custom) |  |
| `scopes` | array<string> |  |
| `lang` | string (tr, en) |  |

### Responses

- **200**: Code issued
- **422**: Validation or business rule failure (`confirm_required`, `invalid_image`, `tool_action_failed` ...)
- **429**: rate_limited

### Examples

```bash
curl -s -X POST 'https://www.gyrohosting.com/api/v1/client/auth/device/code' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client_name": "gyro-cli", "client_version": "1.31.0", "hostname": "laptop", "os": "linux/amd64", "template": "readonly", "scopes": ["cloud_read", "services_read"], "lang": "tr"}'
```
```bash
gyro api request POST /auth/device/code --data '{"client_name": "gyro-cli", "client_version": "1.31.0", "hostname": "laptop", "os": "linux/amd64", "template": "readonly", "scopes": ["cloud_read", "services_read"], "lang": "tr"}'
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.post("https://www.gyrohosting.com/api/v1/client/auth/device/code", headers=h, json={"client_name": "gyro-cli", "client_version": "1.31.0", "hostname": "laptop", "os": "linux/amd64", "template": "readonly", "scopes": ["cloud_read", "services_read"], "lang": "tr"}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/auth/device/code", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"client_name": "gyro-cli", "client_version": "1.31.0", "hostname": "laptop", "os": "linux/amd64", "template": "readonly", "scopes": ["cloud_read", "services_read"], "lang": "tr"}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## POST /auth/device/token

**Poll for the key (device code)** · operationId `pollDeviceToken` · scope `` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/pollDeviceToken.json

No API key. 400 errors while waiting: `authorization_pending` (keep polling every `interval` s), `slow_down` (details.interval is the new interval), `access_denied` (denied in the browser, or the account can no longer get a key), `expired_token`, `invalid_grant` (unknown or already used code). 200 once: the new key (`access_token`).


### Request body

| Field | Type | Description |
|---|---|---|
| `device_code` (required) | string |  |

### Responses

- **200**: Approved: the key, once
- **400**: authorization_pending | slow_down | access_denied | expired_token | invalid_grant
- **429**: rate_limited

### Examples

```bash
curl -s -X POST 'https://www.gyrohosting.com/api/v1/client/auth/device/token' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"device_code": "string"}'
```
```bash
gyro api request POST /auth/device/token --data '{"device_code": "string"}'
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.post("https://www.gyrohosting.com/api/v1/client/auth/device/token", headers=h, json={"device_code": "string"}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/auth/device/token", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"device_code": "string"}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## GET /auth/session

**Key in use: account, permissions, expiry** · operationId `getAuthSession` · scope `` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/getAuthSession.json

Any valid key (no scope needed).


### Responses

- **200**: Session
- **401**: Missing, invalid or revoked key

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/auth/session' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro api request GET /auth/session
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/auth/session", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/auth/session", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## DELETE /auth/session

**Revoke the key in use (sign out)** · operationId `deleteAuthSession` · scope `` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/deleteAuthSession.json

Revokes the key that sends this request (any valid key, no scope needed). It stays listed as revoked on the API Credentials page.


### Responses

- **200**: Revoked
- **401**: Missing, invalid or revoked key

### Examples

```bash
curl -s -X DELETE 'https://www.gyrohosting.com/api/v1/client/auth/session' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro api request DELETE /auth/session
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.delete("https://www.gyrohosting.com/api/v1/client/auth/session", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/auth/session", {
  method: "DELETE",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```