Authentication

Authentication and Authorization

Introduction

This part of the documentation explains how to interact with the API using tokens, API keys, and client IDs. The API requires authentication through an API key, which generates a JWT token containing the client ID and its access level. This token must be used in subsequent requests for secure access.

Authentication Flow

API Key Validation: Clients must include their API key in the request headers.
JWT Token Generation: The server generates a JWT token upon successful API key validation.
Token Usage: The JWT token must be included in the Authorization header for subsequent requests.

Getting Started

API Key

Each client is provided with a unique API key. This key must be included in the X-API-Key header for authentication.

Client ID

The Client ID is associated with the API key and included in the JWT token. This ID is used to identify and authorize specific actions.

Endpoints

Retrieve Client ID

Request

URL: /api/v1/auth/

Method: GET

Headers: - X-API-Key: Your unique API key

API Response:

{ client_id: "your_client_ID", access_level: "your_access_level" }

Example using `requests` in Python

import requests

# Define the URL and the endpoint
url = "http://<ROBOT_IP>:8000/api/v1/auth/"

# Define the headers with the API key
headers = {
    "X-API-Key": "your_api_key_here"
}

# Make the GET request
response = requests.get(url, headers=headers)

# Print the response
print(response.json())

# Get the JWT token from the response headers
jwt_token = response.headers.get("Authorization").split()[1]
print(f"JWT Token: {jwt_token}")

Example using `curl`

curl -X GET "http://<ROBOT_IP>:8000/api/v1/auth/" -H "X-API-Key: your_api_key_here"

Using the JWT Token for Subsequent Requests

After obtaining the JWT token, include it in the Authorization header for all subsequent requests.

Example using POST method and `requests` in Python

import requests
import jwt

# Define the URL and the endpoint
url = "http://<ROBOT_IP>:8000/api/v1/coordinates/"

# Define the headers with the JWT token
headers = {
    "Authorization": f"Bearer {jwt_token}"
}

# Define the payload/data to send with the request
data = {"command": "go_to_relative", "value": {"x": 1.5, "y": -0.5, "z": 0.0, "theta": 3.14}}

# Make the POST request
response = requests.post(url, json=data, headers=headers)

# Print the response
print(response.json())

Example using POST method with `curl`

curl -X POST "http://<ROBOT_IP>:8000/api/v1/coordinates/" \
-H "Authorization: Bearer <JWT_TOKEN>" \
-H "Content-Type: application/json" \
-d '{"command": "go_to_relative", "value": {"x": 1.5, "y": -0.5, "z": 0.0, "theta": 3.14}}'

Security Best Practices

Keep Your API Key Secure: Never share your API key publicly. Treat it as sensitive information.
Use HTTPS: Always use HTTPS to encrypt your API requests and responses.
Token Expiration: The JWT token includes an expiration time (30mn). Make sure to handle token expiration in your client application by requesting a new token when needed.
Token Storage: Store the JWT token securely in your client application. Avoid storing it in locations that are easily accessible, such as local storage or cookies.

Conclusion

This documentation provides the necessary steps to authenticate and interact with the API securely. By following these guidelines and using the provided examples, clients can ensure secure and authenticated communication with the API.