Skip to main content

Platform API Authentication (JWT)

The vitalera REST API uses JWT (JSON Web Token) authentication based on the OAuth 2.0 standard.

Obtaining Credentials​

Contact support@vitalera.io to request:

  • Client ID — identifies your application
  • Client Secret — authenticates your application
  • Application ID — used for credential rotation

Client Credentials Grant​

For server-to-server (machine-to-machine) integrations:

curl -X POST "https://api.vitalera.io/api/auth/tokens/" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "client_credentials",
           "client_id": "<CLIENT_ID>",
           "client_secret": "<CLIENT_SECRET>"
         }'

Response:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Password Grant​

For user login flows (e.g., mobile or web apps authenticating individual users):

curl -X POST "https://api.vitalera.io/api/auth/tokens/" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type": "password",
           "username": "<USERNAME>",
           "password": "<PASSWORD>"
         }'

Response:

{
  "id_token": "<ID_TOKEN>",
  "access_token": "<ACCESS_TOKEN>",
  "refresh_token": "<REFRESH_TOKEN>",
  "sub": "<USER_ID>"
}

Making API Requests​

Include the access token in the Authorization header of every request:

curl -X GET "https://api.vitalera.io/api/plans/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

Token Validity​

Access tokens are valid for 1 hour (3600 seconds). When a token expires, the API returns HTTP 401 Unauthorized:

{
  "errors": [
    {
      "errorType": "expired_token",
      "message": "Access token expired"
    }
  ]
}

Token Refresh​

If you obtained a refresh token (via password grant), you can refresh your access token without re-authenticating:

curl -X POST "https://api.vitalera.io/api/auth/tokens/refresh/" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
           "refresh_token": "<REFRESH_TOKEN>"
         }'

Token Validation​

Verify that a token is still valid:

curl -X GET "https://api.vitalera.io/api/auth/tokens/validate/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>"

Credentials Rotation​

For security, periodically rotate your client credentials. This requires a valid JWT and the application_id:

curl -X POST "https://api.vitalera.io/api/applications/rotate_credentials/" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "application_id": "<APPLICATION_ID>"
         }'

Response:

{
  "id": "<APPLICATION_ID>",
  "name": "TestApp",
  "organization": "123",
  "client_id": "<NEW_CLIENT_ID>",
  "client_secret": "<NEW_CLIENT_SECRET>",
  "application_types": ["API"]
}

After rotation, the previous credentials are invalidated immediately.

Need Help?​

Reach out to support@vitalera.io for authentication setup assistance.