# Poll CLI Signup Token

**GET** `/v1/sign_up/{cli_token}`

Returns the account credentials for a minted `cli_token` once signup has completed, and `202 Accepted` until then. The CLI calls this endpoint repeatedly after sending the user to the `signup_url` returned by `POST /sign_up`.

* `202 Accepted`. The accounts service has not propagated the user yet, or has propagated the user but not minted the first API key. Keep polling. An unknown token also returns `202`, because the API does not record a token at mint time, so the CLI must set its own polling deadline.
* `200 OK`. The user and first API key exist. The API returns the credentials once. Later polls return `410 Gone`.
* `410 Gone`. The token has expired or has already been claimed.

## Example request

**URL**

```http
https://api.ideal-postcodes.co.uk/v1/sign_up/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

**curl**

```bash
curl 'https://api.ideal-postcodes.co.uk/v1/sign_up/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
```

**JavaScript**

```javascript
const response = await fetch('https://api.ideal-postcodes.co.uk/v1/sign_up/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...');

const { result } = await response.json();
```

**Python**

```python
import requests

response = requests.get("https://api.ideal-postcodes.co.uk/v1/sign_up/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
result = response.json()["result"]
```

**Ruby**

```ruby
require "net/http"
require "json"

uri = URI("https://api.ideal-postcodes.co.uk/v1/sign_up/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
result = JSON.parse(Net::HTTP.get(uri))["result"]
```

**PHP**

```php
<?php
$response = file_get_contents("https://api.ideal-postcodes.co.uk/v1/sign_up/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");
$result = json_decode($response, true)["result"];
```

## Example response

**200 OK**

```json
{
  "code": 2000,
  "message": "Success",
  "result": {
    "user_token": "",
    "test_api_key": "",
    "user_id": ""
  }
}
```

**202 Pending**

response.json

```json
{
  "code": 2020,
  "message": "Pending",
  "result": {
    "status": "pending"
  }
}
```

**410 Gone**

response.json

```json
{
  "code": 4100,
  "message": "Token expired or already claimed"
}
```

## Path parameters

* `cli_token` string

  The token returned by `POST /sign_up`.

## Response

Responses vary by status:

### Success (200)

`result` contains the user credentials once signup is complete and Rails has propagated the user to the API.

* `result` object

  | Field          | Type   | Description                                                    |
  | -------------- | ------ | -------------------------------------------------------------- |
  | `user_token`   | string | User-level token used to manage account resources via the api. |
  | `test_api_key` | string | Initial test API key for the account.                          |
  | `user_id`      | string | Internal api user id.                                          |

Credentials are returned exactly once. Subsequent polls with the same token return `410 Gone`.

### Pending (202)

Signup is still in progress. Keep polling.

response.json

```json
{
  "code": 2020,
  "message": "Pending",
  "result": {
    "status": "pending"
  }
}
```

### Expired or Claimed (410)

Token has expired or has already been claimed.

response.json

```json
{
  "code": 4100,
  "message": "Token expired or already claimed"
}
```

The standard `{ result, code, message }` envelope is described in the [API reference](/docs/api/api-reference.md).

## Polling Strategy

The CLI is responsible for:

* Polling at a reasonable interval (suggest 1–2 second backoff)
* Implementing a polling deadline (e.g., 10 minutes)
* Stopping when a `200`, `410`, or timeout occurs

The API does not record the `cli_token` at mint time — it only becomes known to the API once Rails propagates the user. A `202 Accepted` can persist indefinitely if the user never completes signup. Set a deadline on the CLI side.