API Authentication

Learn how to authenticate with the AchieveApex API using JWT authentication.

Authentication Method

AchieveApex uses JSON Web Tokens (JWT) for REST API authentication. This provides a secure and stateless method for authenticating API requests.

Authentication Endpoints

The main authentication endpoint is /authentication. This endpoint handles both login and JWT verification.

Email/Password Authentication

To authenticate with email and password, send a POST request to the authentication endpoint with the strategy set to "local".

curl -X POST https://api.achieveapex.com/authentication \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "local",
    "email": "user@example.com",
    "password": "your-password"
  }'

If successful, the server will respond with the authenticated user and a JWT:

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9...",
  "authentication": {
    "strategy": "local"
  },
  "user": {
    "id": 123,
    "email": "user@example.com",
    "name": "Example User",
    "avatar": "https://example.com/avatar.jpg",
    "createdAt": "2023-01-01T00:00:00.000Z",
    "updatedAt": "2023-01-01T00:00:00.000Z"
  }
}

JWT Re-authentication

Once you have a JWT, you can use it to authenticate subsequent requests without needing to provide credentials again.

curl -X POST https://api.achieveapex.com/authentication \
  -H "Content-Type: application/json" \
  -d '{
    "strategy": "jwt",
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9..."
  }'

The response will be similar to the initial authentication response.

Making Authenticated Requests

To make authenticated requests to the API, include the JWT in the Authorization header:

curl -X GET https://api.achieveapex.com/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9..." \
  -H "Content-Type: application/json"

Logging Out

To log out and invalidate your JWT:

curl -X DELETE https://api.achieveapex.com/authentication \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9..." \
  -H "Content-Type: application/json"

Error Handling

When authentication fails, the API will return appropriate HTTP status codes and error messages:

{
  "name": "NotAuthenticated",
  "message": "Invalid login",
  "code": 401,
  "className": "not-authenticated",
  "errors": {}
}

{
  "name": "NotAuthenticated",
  "message": "jwt expired",
  "code": 401,
  "className": "not-authenticated",
  "errors": {}
}

Common HTTP Status Codes

Security Considerations

• Always use HTTPS in production to prevent token interception.
• Store JWTs securely on the client-side.
• Implement token refresh mechanisms for long-lived sessions.
• Set appropriate token expiration times.