Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/OluwagbeminiyiA/agro_pulse-API/llms.txt

Use this file to discover all available pages before exploring further.

AgroPulse authenticates requests using JSON Web Tokens (JWT) issued by the SimpleJWT library. Every protected endpoint requires a valid access token in the Authorization header. Access tokens are short-lived; when they expire you use a refresh token to obtain a new one without asking the user to log in again. Tokens are issued against a specific user account and carry that user’s role (BUYER, SELLER, or TRANSPORTER), which the API uses to enforce access control.

​
Obtain a token

Send the user’s email and password to /api/token/. On success the API returns both an access token and a refresh token. 
curl -s -X POST http://localhost:8000/api/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "securepassword123"
  }'
Response: 
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Pass the token in requests

Include the access token in the Authorization header of every request to a protected endpoint. The scheme must be Bearer. 
curl -s http://localhost:8000/api/produces/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Refresh an expired token

When the access token expires, use the refresh token to obtain a new one without re-entering credentials. Send the refresh token to /api/token/refresh/. 
curl -s -X POST http://localhost:8000/api/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'
Response: 
{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

​
Token lifetimes

SimpleJWT ships with a default access token lifetime of 5 minutes and a refresh token lifetime of 1 day. Your deployment may override these values in SIMPLE_JWT settings. Check with your administrator if you are unsure what lifetimes are in effect.
TokenDefault lifetime
Access5 minutes
Refresh1 day
Build your client to detect 401 Unauthorized responses and automatically call /api/token/refresh/ before retrying the original request.

​
Authentication errors

StatusMeaningCommon cause
401 UnauthorizedToken absent, malformed, or expiredMissing Authorization header; expired access token not yet refreshed
403 ForbiddenToken valid but insufficient permissionsAuthenticated user’s role does not have access to the requested endpoint
A 403 Forbidden response does not mean the token has expired — it means the authenticated user’s role does not permit the action. Refreshing the token will not resolve a permission error. Verify that the user account has the correct role for the endpoint.

​
Role-based access

Every user account has a role field set at registration time. The API enforces role-based access control on each endpoint:
RoleDescription
BUYERCan browse produce, place orders, and initialize payments.
SELLERCan create and manage produce listings and fulfil orders. Registered as a SELLER; displayed as “farmer” in the data model.
TRANSPORTERCan accept delivery assignments and update delivery status.
The role cannot be changed after registration. If a user requires a different role, create a new account with the correct role. For a full breakdown of which endpoints each role can access, see User roles.

Build docs developers (and LLMs) love

Get started for freeTalk to us