Authentication

The Osigu API uses OAuth 2.0 to secure access to its endpoints. To interact with the API, clients must authenticate by obtaining an access token using the client credentials grant type. This flow is used for machine-to-machine communication, where you’ll provide a client ID and client secret to receive an access token.

Once authenticated, you must include the access token in the Authorization header of all subsequent API requests.

Obtaining an Access Token (Client Credentials)

To obtain an access token in the sandbox environment, make a POST request to the following URL:

https://sandbox.osigu.com/v1/oauth/token?grant_type=client_credentials

The Authorization header must contain a Base64-encoded string of your client_id and client_secret, formatted as follows:

Authorization: Basic Base64(client_id:client_secret)

Example request (Sandbox)

curl --location --request POST 'https://sandbox.osigu.com/v1/oauth/token?grant_type=client_credentials' \
--header 'Authorization: Basic Y29zc2VuLW9zaWd1LXNlcnZpY2U6YmFzZTY0c2VjcmV0a2V5'

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class OAuthTokenExample {
    public static void main(String[] args) throws Exception {
        // Create HTTP client
        HttpClient client = HttpClient.newHttpClient();
        
        // Build the request
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://sandbox.osigu.com/v1/oauth/token?grant_type=client_credentials"))
            .header("Authorization", "Basic Y29zc2VuLW9zaWd1LXNlcnZpY2U6YmFzZTY0c2VjcmV0a2V5")
            .POST(HttpRequest.BodyPublishers.noBody())
            .build();
        
        // Send the request and get the response
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        
        // Print the response body
        System.out.println(response.body());
    }
}

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Threading.Tasks;

class Program
{
    private static readonly HttpClient client = new HttpClient();

    static async Task Main(string[] args)
    {
        // Set up the request
        var request = new HttpRequestMessage(HttpMethod.Post, "https://sandbox.osigu.com/v1/oauth/token?grant_type=client_credentials");
        request.Headers.Authorization = new AuthenticationHeaderValue("Basic", "Y29zc2VuLW9zaWd1LXNlcnZpY2U6YmFzZTY0c2VjcmV0a2V5");

        // Send the request
        HttpResponseMessage response = await client.SendAsync(request);

        // Ensure the request was successful
        response.EnsureSuccessStatusCode();

        // Get and print the response content
        string responseBody = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseBody);
    }
}

import requests

url = "https://sandbox.osigu.com/v1/oauth/token?grant_type=client_credentials"
headers = {
    "Authorization": "Basic Y29zc2VuLW9zaWd1LXNlcnZpY2U6YmFzZTY0c2VjcmV0a2V5"
}

# Send the POST request
response = requests.post(url, headers=headers)

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

Basic Authorization: The header contains a Base64-encoded string of your client_id and client_secret.
Example (not real credentials): Y29zc2VuLW9zaWd1LXNlcnZpY2U6YmFzZTY0c2VjcmV0a2V5

Replace the example Authorization value with your actual Base64-encoded credentials.

Example respose

If the credentials are correct, the server will return a response containing the access token:

{
    "access_token": "20c53bc6-641e-4965-9473-bde902befac4",
    "token_type": "bearer",
    "expires_in": 86399,
    "scope": "read write"
}

access_token: The token you’ll use to authenticate API requests.
token_type: Will always be bearer.
expires_in: The number of seconds until the token expires (typically 24 hours).
scope: The granted permissions for the token.

Using the Access Token

Once you’ve obtained the access token, include it in the Authorization header for all API requests as follows:

Authorization: Bearer <access_token>

Example (Using the access token)

curl --location --request GET 'https://sandbox.osigu.com/v1/invoices' \
--header 'Authorization: Bearer 20c53bc6-641e-4965-9473-bde902befac4'

Token Expiration and Renewal

The access token is valid for 24 hours (expires_in 86399 seconds). Once it expires, you must request a new one by making the same authentication request.

Do not store your client credentials directly in public or unprotected environments for security reasons.