Guide: Authentication

The Tideform API is protected by a security layer that’s managed automatically in the GraphQL UI when you log in. For programmatic access, however, you’ll need to authenticate.

The API uses the OAuth2.0 protocol for authentication, and supports the use of the Authorization Client Credentials flow.

The following example demonstrates how to use the Authorization Client Credentials flow to authenticate with the API using javascript. This is a simple example, but there are however many libraries that support doing the client credentials flow for you.

Managing OAuth2 clients

Using the Portal under the "My Organization" section, at the bottom, you can create and manage your OAuth2 clients and the Client ID and Client Secret.

Click the "+Add" button to create a new client. Give it a descriptive name and click "Create client" to obtain the Client ID and Client Secret.

N.B. remember to copy the client secret, this is the only chance you get to see it.

JavaScript example

/**
 * Fetches spot price data from the Tideform API using OAuth2.0 authentication.
 * This function demonstrates the complete flow from obtaining an access token
 * to making an authenticated GraphQL query.
 *
 * @returns {Promise<Object>} The spot price data response from the GraphQL API
 */
async function getSpotPrice() {
  // Set up parameters for OAuth token request
  const qs = new URLSearchParams();
  qs.set("grant_type", "client_credentials");
  // Use environment variables for credentials if available, fallback to example values
  qs.set("client_id", process.env.CLIENT_ID || "some-client-id");
  qs.set("client_secret", process.env.CLIENT_SECRET || "some-client-secret");

  // Request OAuth access token
  const response = await fetch("https://auth.nexusdigit.al/oauth2/token", {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
    },
    body: qs.toString(),
  });

  const data = await response.json();
  const access_token = data.access_token;

  // Make authenticated GraphQL query to fetch spot price data
  // This example queries Singapore (SGSIN) port's MGO fuel spot price
  const spotResponse = await fetch("https://api.tideform.io/graphql", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${access_token}`, // Include OAuth token for authentication
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      operationName: "spotPrice",
      query: `query spotPrice {
        port(id: "SGSIN") {
            coordinates {
                latitude
                longitude
            }
            fuelPortProfile(fuelGradeId: "MGO") {
                spot {
                    currency
                    name
                    latestPrice {
                        publishedDate
                        price
                    }
                }
            }
        }
      }`,
    }),
  });

  return await spotResponse.json();
}

// Execute the function and log the result
getSpotPrice().then(console.log);

Python example

import os
import aiohttp


async def get_spot_price():
    """
    Fetches spot price data from the Tideform API using OAuth2.0 authentication.
    This function demonstrates the complete flow from obtaining an access token
    to making an authenticated GraphQL query.

    Returns:
        dict: The spot price data response from the GraphQL API
    """
    # Set up the token request parameters
    token_url = "https://auth.nexusdigit.al/oauth2/token"
    token_data = {
        "grant_type": "client_credentials",
        "client_id": os.getenv("CLIENT_ID", "some-client-id"),
        "client_secret": os.getenv("CLIENT_SECRET", "some-client-secret"),
    }

    async with aiohttp.ClientSession() as session:
        # Request the OAuth access token
        async with session.post(
            token_url,
            data=token_data,
            headers={"Content-Type": "application/x-www-form-urlencoded"},
        ) as token_response:
            token_data = await token_response.json()
            access_token = token_data["access_token"]

        # Set up the GraphQL query
        # This example queries Singapore (SGSIN) port's MGO fuel spot price
        graphql_url = "https://api.tideform.io/graphql"
        graphql_query = {
            "operationName": "spotPrice",
            "query": """query spotPrice {
                port(id: "SGSIN") {
                    coordinates {
                        latitude
                        longitude
                    }
                    fuelPortProfile(fuelGradeId: "MGO") {
                        spot {
                            currency
                            name
                            latestPrice {
                                publishedDate
                                price
                            }
                        }
                    }
                }
            }""",
        }

        # Make authenticated GraphQL query to fetch spot price data
        async with session.post(
            graphql_url,
            json=graphql_query,
            headers={
                "Authorization": f"Bearer {access_token}",
                "Content-Type": "application/json",
            },
        ) as spot_response:
            spot_data = await spot_response.json()

    return spot_data


# Execute the function
result = await get_spot_price()