Authentication API

The Authentication API allows you to obtain the necessary tokens to access the Nilo platform. This endpoint is essential for starting to use any other API service.

Understanding Authentication

Authentication in Nilo uses a two-factor approach to ensure secure access to the platform:

Credential	Description
API Key	Static key passed in x-api-key header. Unique per environment.
Access Token	Dynamic JWT token passed in Authorization header. Has limited lifespan.

Important Considerations

1. Token Lifecycle: Access tokens expire after a set time and need to be renewed
2. Security: Never share your API keys or client credentials
3. Permissions: Different operations require different permission scopes
4. Rate Limiting: Authentication requests may be rate-limited
5. Environment Separation: Different credentials are required for each environment

Authentication Flow

1. Obtain your API key, client ID, and client secret
2. Make a login request to obtain an access token
3. Include both the API key and access token in subsequent requests
4. Renew the access token before it expires

Get Token

POST/login

This endpoint is used to obtain an authentication token that will allow you to access the API. The token obtained must be included in the Authorization header of subsequent requests.

Request Body Parameters

Parameter	Type	Required	Description
clientId	string	Yes	Client ID
clientSecret	string	Yes	Secret key

Request Body Example

{
  "clientId": "tu-client-id",
  "clientSecret": "tu-clave-secreta"
}

Response Codes

Code	Description
200	Operation successful - Token generated correctly
401	Unauthorized - Invalid credentials

Example Usage

Javascript

const headers = {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

const data = {
  clientId: "tu-client-id",
  clientSecret: "tu-clave-secreta",
};

fetch("https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/login", {
  method: "POST",
  headers: headers,
  body: JSON.stringify(data),
})
  .then((response) => response.json())
  .then((result) => console.log(result))
  .catch((error) => console.log("error", error));

Python

import requests

url = "https://tm0cs5kjs6.execute-api.us-east-1.amazonaws.com/dev/login"

headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}

data = {
    "clientId": "tu-client-id",
    "clientSecret": "tu-clave-secreta"
}

response = requests.post(url, headers=headers, json=data)
print(response.text)

Try the Endpoint

Test the authentication endpoint

API Key:

Client ID:

Secret:

Response:

Success Response Example

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error Response Example

{
  "code": 401,
  "message": "Unauthorized"
}

Best Practices

1. Token Management

   • Store tokens securely
   • Implement token refresh before expiration
   • Never store tokens in client-side code
   • Use environment variables for credentials

2. Error Handling

   • Implement proper error handling for authentication failures
   • Add retry logic with exponential backoff
   • Monitor token expiration
   • Log authentication errors for debugging

3. Security Measures

   • Use HTTPS for all requests
   • Rotate credentials periodically
   • Implement request signing when required
   • Monitor for unusual authentication patterns

4. Performance Optimization

   • Cache tokens until near expiration
   • Implement token refresh in background processes
   • Use connection pooling for authentication requests
   • Batch operations to minimize authentication overhead

Common Use Cases

1. Initial Setup

   • Generate API credentials
   • Implement authentication flow
   • Set up secure credential storage
   • Configure environment-specific settings

2. Production Deployment

   • Migrate from sandbox to production credentials
   • Implement proper security measures
   • Set up monitoring and alerting
   • Configure backup authentication methods

3. Multi-Environment Management

   • Manage different credentials per environment
   • Implement environment-specific configurations
   • Set up credential rotation schedules
   • Configure failover mechanisms

4. Troubleshooting

   • Monitor authentication failures
   • Debug token expiration issues
   • Track rate limiting problems
   • Analyze security incidents

Response Types

Success Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Error Response Examples

Invalid Credentials

{
  "code": 401,
  "message": "Invalid client credentials"
}

Rate Limited

{
  "code": 429,
  "message": "Too many requests"
}

Expired Token

{
  "code": 401,
  "message": "Unauthorized"
}

Security Recommendations

1. Credential Storage

   • Use secure credential vaults
   • Encrypt sensitive data at rest
   • Implement access controls
   • Regular security audits

2. Request Security

   • Validate SSL certificates
   • Implement request signing
   • Use secure communication channels
   • Monitor for security breaches

3. Access Control

   • Implement role-based access
   • Regular permission audits
   • Monitor unusual activity
   • Implement IP whitelisting

4. Compliance

   • Follow security best practices
   • Implement audit logging
   • Regular security reviews
   • Maintain compliance documentation

Using the Token

The token obtained must be included in all subsequent requests as an authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Security

All API endpoints require two types of authentication:

1. API Key in header: x-api-key
2. Authorization token in header: Authorization

Token Expiration

The token has a limited lifespan, specified in the expiresIn field of the response (in seconds). You will need to request a new token once the current one has expired.

---

Next Steps

🏷️

Create Brands

Start by creating your first brand

→📦

Manage Products

Add products to your catalog

→