# Session (Coinbax Core API)

> Source: https://developers.coinbax.com/reference/coinbax-core/session/
> Staging base URL: https://core-staging.coinbax.com

The caller's own session lifecycle: who am I, refresh, log out. This is
the slice of authentication an integrator needs. Account administration
(register, password reset, OAuth account linking) stays private.


## Sign up for a staging account

`POST /auth/signup`

- Auth: Bearer token
- Operation ID: `authSignup`

Self-serve signup. Creates the account and sends a verification code.
On staging the code is also returned in the response so the flow can be
completed without an inbox; in production it is email-only.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `password` | string | yes | Requires upper, lower, number and special characters. |
| `firstName` | string | yes |  |
| `lastName` | string | yes |  |
| `companyName` | string | no |  |
| `intendedUseCase` | string | no |  |
| `waitlistReason` | string | no |  |

```json
{
  "email": "developer@example.com",
  "password": "string",
  "firstName": "string",
  "lastName": "string",
  "companyName": "string",
  "intendedUseCase": "string",
  "waitlistReason": "string"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/auth/signup \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "developer@example.com",
  "password": "string",
  "firstName": "string",
  "lastName": "string",
  "companyName": "string",
  "intendedUseCase": "string",
  "waitlistReason": "string"
}'
```

### Responses

**201** Account created; verification code issued

**400** Validation failed

**409** An account with that email already exists

---

## Redeem an email verification code

`POST /auth/verify-code`

- Auth: Bearer token
- Operation ID: `authVerifyCode`

Runs the same verification the emailed link performs and provisions the
identity so the account can sign in. Idempotent: a transient failure
preserves the code so the call can be retried.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes |  |
| `code` | string | yes |  |

```json
{
  "email": "developer@example.com",
  "code": "string"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/auth/verify-code \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "developer@example.com",
  "code": "string"
}'
```

### Responses

**200** Verified; the account can now sign in

**400** Code invalid or expired

---

## Log in and obtain tokens

`POST /identity/login`

- Auth: Bearer token
- Operation ID: `identityLogin`

Authenticate with email and password and receive an access/refresh token
pair. This is the current auth path — the identity service is the single
source of truth for accounts since the Phase 5 cutover.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | Normalised to lowercase server-side. |
| `password` | string | yes |  |
| `environment` | string | no | Optional identity environment selector. |

```json
{
  "email": "you@example.com",
  "password": "<your-password>"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/identity/login \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "you@example.com",
  "password": "<your-password>"
}'
```

### Responses

**200** Authenticated; tokens returned

**401** Invalid credentials

---

## Invalidate the current session

`POST /identity/logout`

- Auth: Bearer token
- Operation ID: `identityLogout`

Invalidates the refresh token immediately. The access token remains
valid until it expires.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refreshToken` | string | yes |  |

```json
{
  "refreshToken": "string"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/identity/logout \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string"
}'
```

### Responses

**200** Session invalidated

---

## Get the authenticated account

`GET /identity/me`

- Auth: Bearer token
- Operation ID: `identityMe`

Returns the account behind the presented access token.

### Example request

```bash
curl https://core-staging.coinbax.com/identity/me \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Account returned

**401** Missing or invalid access token

---

## Exchange a refresh token for a new access token

`POST /identity/refresh`

- Auth: Bearer token
- Operation ID: `identityRefresh`

Access tokens are short-lived. Exchange the refresh token rather than
re-prompting for credentials.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refreshToken` | string | yes |  |
| `environment` | string | no |  |

```json
{
  "refreshToken": "string",
  "environment": "string"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/identity/refresh \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string",
  "environment": "string"
}'
```

### Responses

**200** New tokens issued

**401** Refresh token invalid or expired