> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.shimi.cash/api-reference/shimi-api/authentication/generate-access-token/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.shimi.cash/_mcp/server.

# Generate Access Token

POST https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/{reference}

Exchange your API key for a short-lived access token and a refresh token. Call this once at the start of your integration, and again any time your refresh token itself expires or is revoked.

**Path parameter:** `reference` — your company reference (given to you at onboarding).

**Header:** `x-api-key` — your API key (given to you at onboarding). Keep this secret; it never leaves your backend.

**Errors:** `400` API key missing · `401` API key expired or invalid · `403` company reference not found.

**Path parameter**

| Field       | Type          | Required | Notes                                                                               |
| ----------- | ------------- | -------- | ----------------------------------------------------------------------------------- |
| `reference` | string (cuid) | yes      | Your company ID (issued at onboarding). The API key record is looked up by this ID. |

**Header:** `x-api-key` (string, required) - your plain-text API key; compared against a bcrypt hash.

**No request body.**

**Behaviour notes**

* Success returns `{ accessToken, refreshToken }` (HTTP 200). Each call rotates the stored refresh token: any refresh token issued earlier stops working.
* An unknown `reference` returns `400 Bad Request: API key is missing` (not 403) because no API-key record exists for it.
* Expired API key: `401` with message `Bad Request: API KEY EXPIRED`. Wrong key: `401 Unauthorized: Invalid API key`.
* Tokens are refused unless the business is live **and** KYB status is `APPROVED` or `CHANGES_REQUESTED`. `403 ACCOUNT_DEACTIVATED` is returned only when KYB is `APPROVED` but the account is switched off; every other refusal is `403 KYB_REQUIRED` with the current `kybStatus` (`NOT_STARTED`, `IN_PROGRESS`, `SUBMITTED`, `CHANGES_REQUESTED`, `REJECTED`).
* Unexpected server errors come back as `400 { "message": "Internal Server Error" }`.

**Errors that apply to every authenticated endpoint** (shown here once): `401 Access token is missing` (no `Authorization: Bearer` header), `403 Invalid or expired access token`, `403` KYB / deactivated bodies as below (cached for up to 30 s), and `503 Service temporarily unavailable` if the KYB check itself fails.

Reference: https://docs.shimi.cash/api-reference/shimi-api/authentication/generate-access-token

## Request

### Path parameters

- `reference` (string, required) — Your company reference, issued at onboarding.

### Headers

- `x-api-key` (string, required)

## Response

### 200

OK

- `accessToken` (string, optional)
- `refreshToken` (string, optional)

## Errors

### 400 Bad Request Error

API key header missing / Unknown company reference

- `message` (string, optional)

### 401 Unauthorized Error

API key expired / Invalid API key / Access token missing (any authenticated endpoint)

- `message` (string, optional)

### 403 Forbidden Error

KYB not approved / Account deactivated / Company not found / Invalid or expired access token (any authenticated endpoint)

- `code` (string, optional)
- `kybStatus` (string, optional)
- `message` (string, optional)

### 503 Service Unavailable Error

Service Unavailable

- `message` (string, optional)

## Examples

**Response**

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcmVuY2UiOiJjbWcxYTdyMmswMDAwYWIxMmNkMzRlZjU2IiwiaWF0IjoxNzkxMTE1MjAwLCJleHAiOjE3OTExMTg4MDB9.4fT0nR8qWz3m1Xk7pLcV2bH9yJdE6sGuA5oYtKiN0Qw",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZlcmVuY2UiOiJjbWcxYTdyMmswMDAwYWIxMmNkMzRlZjU2IiwiaWF0IjoxNzkxMTE1MjAwLCJleHAiOjE3OTE3MjAwMDB9.Zp3Lq8Vn2Rt6Yw1Hx9Kc4Mb7Jf0Gd5Sa2Ue8Io3Py6"
}
```

**SDK Code**

```python 200 Success
import requests

url = "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/reference"

headers = {"x-api-key": "x-api-key"}

response = requests.post(url, headers=headers)

print(response.json())
```

```javascript 200 Success
const url = 'https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/reference';
const options = {method: 'POST', headers: {'x-api-key': 'x-api-key'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go 200 Success
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/reference"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("x-api-key", "x-api-key")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby 200 Success
require 'uri'
require 'net/http'

url = URI("https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/reference")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = 'x-api-key'

response = http.request(request)
puts response.read_body
```

```java 200 Success
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/reference")
  .header("x-api-key", "x-api-key")
  .asString();
```

```php 200 Success
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/reference', [
  'headers' => [
    'x-api-key' => 'x-api-key',
  ],
]);

echo $response->getBody();
```

```csharp 200 Success
using RestSharp;

var client = new RestClient("https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/reference");
var request = new RestRequest(Method.POST);
request.AddHeader("x-api-key", "x-api-key");
IRestResponse response = client.Execute(request);
```

```swift 200 Success
import Foundation

let headers = ["x-api-key": "x-api-key"]

let request = NSMutableURLRequest(url: NSURL(string: "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/reference")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```