> ## Documentation Index
> Fetch the complete documentation index at: https://docs.transaction.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Learn how to authenticate with Transaction API

## Overview

Transaction API supports two authentication methods depending on the endpoint you're using:

* **JWT Authentication** - For user account operations
* **API Key Authentication** - For payment and merchant operations

## JWT Authentication

JWT tokens are used for user account operations like registration, login, and profile management.

### Getting a JWT Token

<Steps>
  <Step title="Register or Login">
    Use the `/auth/register` or `/auth/login` endpoints to get a JWT token.
  </Step>

  <Step title="Include in Headers">
    Add the token to the `Authorization` header:

    ```
    Authorization: Bearer <jwt_token>
    ```
  </Step>
</Steps>

### Example

```bash theme={null}
# Login to get JWT token
curl -X POST https://api.transaction.gg/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "password123"
  }'

# Use JWT token for authenticated requests
curl -X GET https://api.transaction.gg/auth/me \
  -H "Authorization: Bearer jwt_token_here"
```

## API Key Authentication

API keys are used for payment processing and merchant operations.

### API Key Types

<Columns cols={2}>
  <Card title="Public Key" icon="eye">
    **Format:** `pk_*`

    Used for:

    * Creating payments
    * Public operations

    <Warning>Safe to use in client-side code</Warning>
  </Card>

  <Card title="Secret Key" icon="lock">
    **Format:** `sk_*`

    Used for:

    * Merchant operations
    * Wallet management
    * Webhook logs

    <Warning>Never expose in client-side code</Warning>
  </Card>
</Columns>

### Getting API Keys

1. Log in to your [dashboard](https://dashboard.transaction.gg)
2. Navigate to **API Keys** section
3. Copy your public and secret keys

### Example

```bash theme={null}
# Create payment with public key
curl -X POST https://api.transaction.gg/payment/create \
  -H "Authorization: Bearer pk_your_public_key" \
  -H "Content-Type: application/json" \
  -d '{"amount": "29.99", "currency": "USD"}'

# Check wallet balance with secret key
curl -X GET https://api.transaction.gg/merchant/wallet/balances \
  -H "Authorization: Bearer sk_your_secret_key"
```

## Token Expiration

<Columns cols={2}>
  <Card title="JWT Tokens" icon="clock">
    * Expire after 24 hours
    * Use `/auth/login` to get new token
    * No refresh token mechanism
  </Card>

  <Card title="API Keys" icon="infinity">
    * Do not expire
    * Can be regenerated from dashboard
    * Regeneration invalidates old keys
  </Card>
</Columns>

## Security Best Practices

<Steps>
  <Step title="Store Keys Securely">
    Use environment variables or secure key management systems.
  </Step>

  <Step title="Use HTTPS">
    Always make requests over HTTPS to protect credentials.
  </Step>

  <Step title="Rotate Keys Regularly">
    Regenerate API keys periodically for enhanced security.
  </Step>

  <Step title="Monitor Usage">
    Check your dashboard for unusual API activity.
  </Step>
</Steps>

## Error Handling

Common authentication errors:

| Error Code            | Status | Description                       |
| --------------------- | ------ | --------------------------------- |
| `UNAUTHORISED`        | 401    | Invalid or missing authentication |
| `INVALID_CREDENTIALS` | 401    | Invalid login credentials         |
| `RATE_LIMITED`        | 429    | Too many authentication attempts  |

<Note>
  **Rate Limits:** Authentication endpoints are limited to 5 requests per minute to prevent brute force attacks.
</Note>