/
Authentication

Authentication

Owned by Christian Böhm
Jan 28, 2025
2 min read

 

Authentication is essential for verifying the identity of the client making a request. It helps ensure that only authorized clients can access specific resources and perform certain actions. Our API uses a token-based authentication, where clients must provide an authentication token with each request to validate their identity.

What is an auth token

An Auth Token is a unique identifier issued to a client (like a user or an application) upon successful authentication. This token is usually a long, randomly generated string, often formatted as a JSON Web Token (JWT) or similar encrypted string. Once issued, the token must be included in the headers of subsequent requests to authenticate and authorize access to the API.

Characteristics of Auth Tokens

  • Temporary: Tokens are typically valid for a set duration (e.g., 24 hours) and may need to be refreshed.

  • Secure: Tokens are encrypted to prevent unauthorized access and tampering.

How to get an auth token

To obtain an authentication token, follow these steps:

  1. Endpoint for Authentication: Our API provides an endpoint /auth to authenticate a user or application.
    The client needs to send valid credentials, such as a username and password in the request body.
    Request Example: A typical request to obtain an auth token may look like this:

    GET /v1/auth Content-Type: application/json { "username": "johndoe", "password": "yourpassword" }

  2. Response: Upon successful authentication, the server will respond with a token in JSON format:

    { "access_token": "eyJhbGciOiJ...", "refresh_token": "eyJ0eXAiOiJ..." }

  3. Token Usage: Store this token securely, as it will need to be included in the Authorization header of each API request:

    Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration & Renewal

The token expires after a specified period (currently 12 hours), so you need to re-authenticate or use the refresh token endpoint to obtain a new token without resubmitting credentials. The refresh token is currently valid for 13 hours. Alternatively you can also simply re-authenticate by just using (again) the same method as explained above.

Code example

Get an auth token

import requests # Step 1: Endpoint for Authentication # Configurations username = "your_username" password = "your_password" auth_endpoint = "https://api.hydrogrid.ai/v1/auth" auth_body = { "username": username, "password": password } # Step 2: Response auth_response = requests.post(auth_endpoint, json=auth_body) if auth_response.ok: access_token = auth_response.json().get("access_token") refresh_token = auth_response.json().get("refresh_token") # Step 3: Token Usage print("Token retrieved successfully!") else: print(f"Authentication failed: {auth_response.status_code}") exit()

Token renewal