Nyota Imara authenticates every API request using a JWT Bearer token issued by Supabase after you sign in. This page covers how to attach the token to your requests, how to pass organization context for org-scoped endpoints, and what to do when you receive an authentication or authorization error.
How authentication works
When you sign in at accounts.nyotaimara.com, Nyota Imara issues a signed JWT. The API validates that token on every request automatically. No API key rotation or manual secret management is required on your side — your session token is your credential.
Passing the token
Include the JWT in the Authorization header of every request using the Bearer scheme:
Authorization: Bearer <your-jwt-token>
Example request
curl --request GET \
--url https://api.nyotaimara.com/v1/users/me \
--header "Authorization: Bearer eyJhbGciOiJFUzI1NiIsImtpZCI6Ii..."
Bearer (with a space). Requests without this header, or with a malformed value, return a 401 Unauthorized response.
Organization-scoped endpoints
Many Nyota Imara endpoints operate within the context of a specific organization — billing, commerce, logistics, and team management all require an active org. Pass your organization’s UUID in the X-Organization-Id header alongside your Bearer token:
curl --request GET \
--url https://api.nyotaimara.com/v1/organizations/members \
--header "Authorization: Bearer <your-jwt-token>" \
--header "X-Organization-Id: <your-organization-id>"
Token expiry and refresh
Tokens are short-lived. When your token expires, re-authenticate at accounts.nyotaimara.com to get a fresh one. An expired token returns a 401 error with the message "Unauthorized: Invalid or expired token.".
In production applications, implement automatic token refresh in your client so users are not unexpectedly signed out. Check the token expiry before each request and re-authenticate proactively.
Error responses
401 Unauthorized
A 401 response means the request is missing a valid token or the token could not be verified. This happens when:
- The
Authorization header is missing entirely
- The header does not start with
Bearer
- The token is expired
- The token signature is invalid
Example 401 response:
{
"success": false,
"error": "Unauthorized: Invalid or expired token."
}
403 Forbidden
A 403 response means the token is valid but the authenticated user does not have permission to perform the requested action. This happens when:
- Your account role does not include the required permission for the endpoint
- You are attempting to access a resource that belongs to an organization you are not a member of
- An organization-scoped action requires a higher role (for example, only
owner and admin roles can invite new members)
Example 403 response:
{
"success": false,
"error": "Forbidden: You do not have permission to perform this action."
}
Error reference
| Status | Meaning | Common cause |
|---|
401 Unauthorized | Token is missing, malformed, or expired | No Authorization header, or token has expired |
403 Forbidden | Token is valid but lacks required permissions | Insufficient role within the organization |
Never expose your JWT in client-side code, public repositories, or logs. Treat it with the same care as a password. If a token is compromised, sign out all sessions from your account settings at accounts.nyotaimara.com. 
