# Authentication (Coinbax Core API)

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

User authentication and session management

## User login

`POST /auth/login`

- Auth: Public (no authentication)
- Operation ID: `authLogin`

Authenticate a user with email and password. Returns access token and refresh token.

The access token expires in 1 hour, refresh token in 7 days.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | User's email address |
| `password` | string (password) | yes | User's password (min 8 characters) |

```json
{
  "email": "admin@coinbax.com",
  "password": "admin123"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
  "email": "admin@coinbax.com",
  "password": "admin123"
}'
```

### Responses

**200** Login successful

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "admin@coinbax.com",
      "firstName": "Admin",
      "lastName": "User",
      "role": "ADMIN",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**401** Invalid credentials

**429** Too many requests - rate limit exceeded

**500** Internal server error

---

## Register new user

`POST /auth/register`

- Auth: Public (no authentication)
- Operation ID: `authRegister`

Register a new user account. A verification email will be sent.

**Note:** Registration may be disabled in some deployments.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email` | string (email) | yes | User's email address |
| `password` | string (password) | yes | User's password (min 8 characters) |
| `firstName` | string | yes | User's first name |
| `lastName` | string | yes | User's last name |
| `workspaceName` | string | no | Workspace name (optional, creates new workspace) |

```json
{
  "email": "newuser@example.com",
  "password": "string",
  "firstName": "John",
  "lastName": "Doe",
  "workspaceName": "Acme Corp"
}
```

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
  "email": "newuser@example.com",
  "password": "string",
  "firstName": "John",
  "lastName": "Doe",
  "workspaceName": "Acme Corp"
}'
```

### Responses

**201** Registration successful

```json
{
  "success": true,
  "data": {
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "newuser@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "CLIENT",
      "emailVerified": false
    },
    "message": "Verification email sent"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**400** Bad request - validation error

**409** Email already exists

**429** Too many requests - rate limit exceeded

**500** Internal server error

---

## Get current user

`GET /auth/me`

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

Returns the currently authenticated user's profile information

### Example request

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

### Responses

**200** Current user profile

```json
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "admin@coinbax.com",
    "firstName": "Admin",
    "lastName": "User",
    "role": "ADMIN",
    "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
    "emailVerified": true,
    "avatarPath": "/uploads/avatars/user-123.png",
    "createdAt": "2026-01-15T10:00:00.000Z",
    "updatedAt": "2026-02-20T14:30:00.000Z"
  },
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Refresh access token

`POST /auth/refresh`

- Auth: Public (no authentication)
- Operation ID: `authRefresh`

Exchange a refresh token for a new access token.

The refresh token is single-use and a new refresh token is returned.

### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `refreshToken` | string | yes | The refresh token from login or previous refresh |

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
  "refreshToken": "string"
}'
```

### Responses

**200** Token refreshed successfully

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "accessToken": "string",
    "refreshToken": "string",
    "expiresIn": 3600
  }
}
```

**401** Invalid or expired refresh token

**500** Internal server error

---

## Logout user

`POST /auth/logout`

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

Invalidate the current session and refresh token.

The access token will remain valid until expiration, but the refresh token
will be immediately invalidated.

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/logout \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Logout successful

```json
{
  "success": true,
  "meta": {
    "timestamp": "2026-02-24T12:00:00.000Z",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "totalPages": 8
    }
  },
  "data": {
    "message": "Logged out successfully"
  }
}
```

**401** Unauthorized - missing or invalid authentication

**500** Internal server error

---

## Change password

`POST /auth/change-password`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/change-password \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Password changed

---

## Request password reset

`POST /auth/request-password-reset`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/request-password-reset \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Reset email sent

---

## Reset password

`POST /auth/reset-password`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/reset-password \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Password reset

---

## Verify email address

`POST /auth/verify-email`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/verify-email \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Email verified

---

## Link OAuth provider

`POST /auth/link-oauth`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/link-oauth \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Provider linked

---

## Unlink OAuth provider

`POST /auth/unlink-oauth`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/unlink-oauth \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Provider unlinked

---

## List linked OAuth accounts

`GET /auth/linked-accounts`

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

### Example request

```bash
curl https://core-staging.coinbax.com/api/v1/auth/linked-accounts \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Accounts retrieved

---

## Exchange Google OAuth code

`POST /auth/google/exchange-code`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/google/exchange-code \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Authentication successful

---

## Exchange Microsoft OAuth code

`POST /auth/microsoft/exchange-code`

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

### Example request

```bash
curl -X POST https://core-staging.coinbax.com/api/v1/auth/microsoft/exchange-code \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

### Responses

**200** Authentication successful