# Authentication

Yolcu360 Agency API uses JWT (JSON Web Token) based authentication for secure access. To access the API, you first need
to authenticate with your API credentials and obtain an access token.

## Authentication Flow

1. **Get API Credentials**: Obtain your API key and secret key from the agency portal
2. **Login**: Exchange credentials for JWT tokens using `/auth/login`
3. **Use Access Token**: Include the access token in the Authorization header for all API calls
4. **Refresh Tokens**: Use the refresh token to get new access tokens when they expire


## Login with API Key

Process of obtaining JWT tokens using your API Key and Secret Key.

### Endpoint


```
POST /auth/login
```

### Request Body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `key` | string | Yes | Your API Key obtained from the agency portal |
| `secret` | string | Yes | Your API Secret Key obtained from the agency portal |


### Example Request


```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "key": "your_api_key_here",
    "secret": "your_api_secret_here"
  }'
```

### Response

**Success Response (200 OK):**


```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "dGhpc2lzYXJlZnJlc2h0b2tlbg...",
  "accessTokenExpireAt": "2024-12-26T10:30:00Z",
  "refreshTokenExpireAt": "2024-12-27T10:00:00Z",
  "user": {
    "id": "user_123456",
    "email": "agency@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }
}
```

**Error Responses:**

- `400 Bad Request`: Invalid request format or missing fields
- `401 Unauthorized`: Invalid API key or secret key
- `500 Internal Server Error`: Server error


## Refresh Access Token

When your access token expires, use the refresh token to obtain a new access token without requiring the user to
re-authenticate with API credentials.

### Endpoint


```
POST /auth/refresh
```

### Request Body

| Field | Type | Required | Description |
|  --- | --- | --- | --- |
| `token` | string | Yes | Valid refresh token from the login response |


### Example Request


```bash
curl -X POST https://api.pro.yolcu360.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "token": "dGhpc2lzYXJlZnJlc2h0b2tlbg..."
  }'
```

### Response

**Success Response (200 OK):**


```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "bmV3cmVmcmVzaHRva2VuaGVyZQ...",
  "accessTokenExpireAt": "2024-12-26T11:30:00Z",
  "refreshTokenExpireAt": "2024-12-27T11:00:00Z",
  "user": {
    "id": "user_123456",
    "email": "agency@example.com",
    "firstName": "John",
    "lastName": "Doe"
  }
}
```

**Error Responses:**

- `400 Bad Request`: Invalid request format or missing token
- `401 Unauthorized`: Invalid or expired refresh token
- `500 Internal Server Error`: Server error


## Using Access Tokens

Once you have an access token, include it in the `Authorization` header for all API requests:

### Authorization Header Format


```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

### Example API Call


```bash
curl -X GET https://api.pro.yolcu360.com/api/v1/locations?query=istanbul \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

## Token Expiration and Best Practices

### Access Token Lifecycle

- **Access Token Expiration**: The access token expires after 1 week
- **Refresh Token Expiration**: The refresh token expires after 1 month
- **Automatic Renewal**: Implement automatic token refresh in your application


### Implementation Best Practices

1. **Store Tokens Securely**: Never store tokens in client-side code or logs
2. **Handle Expiration**: Implement automatic refresh logic when receiving 401 errors
3. **Monitor Expiration Times**: Use the `accessTokenExpireAt` field to refresh proactively
4. **Secure Transmission**: Always use HTTPS for authentication requests


### Sample Token Refresh Logic


```javascript
async function makeApiRequest(url, options = {}) {
    let token = getStoredAccessToken();

    // Check if token is close to expiring
    if (isTokenNearExpiry(token)) {
        token = await refreshAccessToken();
    }

    const response = await fetch(url, {
        ...options,
        headers: {
            ...options.headers,
            'Authorization': `Bearer ${token}`
        }
    });

    // Handle expired token
    if (response.status === 401) {
        token = await refreshAccessToken();
        return fetch(url, {
            ...options,
            headers: {
                ...options.headers,
                'Authorization': `Bearer ${token}`
            }
        });
    }

    return response;
}

async function refreshAccessToken() {
    const refreshToken = getStoredRefreshToken();

    const response = await fetch('/api/v1/auth/refresh', {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({token: refreshToken})
    });

    if (!response.ok) {
        // Refresh token expired, need to re-authenticate
        throw new Error('Authentication required');
    }

    const data = await response.json();
    storeTokens(data.accessToken, data.refreshToken);
    return data.accessToken;
}
```

## Security Considerations

### API Key Security

- **Never expose API keys**: Don't include API keys in client-side code, logs, or version control
- **Rotate keys regularly**: Generate new API keys periodically
- **Use environment variables**: Store API credentials in secure environment variables
- **Limit key permissions**: Use the minimum required permissions for your API keys


### Token Security

- **Secure storage**: Store tokens in secure, encrypted storage
- **HTTPS only**: Always use HTTPS for API communications
- **Token scope**: Access tokens are scoped to your organization's resources
- **Logout handling**: Clear stored tokens when users log out


## Error Codes

| Code | Description |
|  --- | --- |
| 1001 | Invalid request format |
| 1002 | Invalid API key or secret key |
| 1003 | API key is disabled or suspended |
| 1004 | Invalid or expired refresh token |
| 1005 | Rate limit exceeded |
| 1500 | Internal server error |


## Troubleshooting

### Common Issues

**Invalid API Key Error**

- Verify your API key and secret key are correct
- Check that your API key is active in the agency portal
- Ensure you're using the correct environment (staging vs production)


**Token Expired Error**

- Implement automatic token refresh logic
- Check token expiration times before making requests
- Handle 401 responses by refreshing tokens