Authentication

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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

Example Request

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):

{
  "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

Example Request

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):

{
  "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

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

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

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