Authentication

The Accuris API uses OAuth 2.0 Client Credentials flow for authentication. This is a server-to-server authentication method where your application exchanges client credentials for an access token that authorizes API requests.

How It Works

The authentication process follows these steps:

1. You receive a Client ID and Client Secret from Accuris during onboarding
2. Your application sends these credentials to the token endpoint
3. The token endpoint validates your credentials and returns an access token
4. You include this access token in the Authorization header of all API requests
5. When the token expires (typically after 1 hour), you request a new one

This flow is designed for backend services and applications where credentials can be securely stored. Never expose your client secret in client-side code or public repositories.

Getting Credentials

API credentials are provided during your onboarding process. You will receive:

• Client ID - Your unique client identifier
• Client Secret - Your secret key (keep this secure and never share it)
• Token Endpoint - The URL to obtain access tokens

There is currently no self-service portal for managing credentials. Contact your Accuris representative for any credential-related requests, including rotation or reset.

Obtaining an Access Token

To authenticate, make a POST request to the token endpoint with your client credentials. The endpoint uses form-encoded data with the OAuth 2.0 client_credentials grant type:

JavaScript

const axios = require("axios");

const TOKEN_ENDPOINT =
  "https://sam.preprod.accuris.dev/sso/oauth2/access_token";
const CLIENT_ID = "your-client-id";
const CLIENT_SECRET = "your-client-secret";

async function getAccessToken() {
  const response = await axios.post(
    TOKEN_ENDPOINT,
    new URLSearchParams({
      grant_type: "client_credentials",
      client_id: CLIENT_ID,
      client_secret: CLIENT_SECRET,
    }),
    {
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
    },
  );

  return response.data.access_token;
}

// Usage
getAccessToken().then((token) => {
  console.log("Access Token:", token);
});

C#

using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;

public class AuthenticationExample
{
    private static readonly string TokenEndpoint = "https://sam.preprod.accuris.dev/sso/oauth2/access_token";
    private static readonly string ClientId = "your-client-id";
    private static readonly string ClientSecret = "your-client-secret";

    public static async Task<string> GetAccessToken()
    {
        using var client = new HttpClient();
        
        var content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("grant_type", "client_credentials"),
            new KeyValuePair<string, string>("client_id", ClientId),
            new KeyValuePair<string, string>("client_secret", ClientSecret)
        });

        var response = await client.PostAsync(TokenEndpoint, content);
        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync();
        // Parse JSON to extract access_token
        // Using System.Text.Json or Newtonsoft.Json recommended
        
        return json; // Extract access_token from JSON
    }
}

Java

import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;

public class AuthenticationExample {
    private static final String TOKEN_ENDPOINT = "https://sam.preprod.accuris.dev/sso/oauth2/access_token";
    private static final String CLIENT_ID = "your-client-id";
    private static final String CLIENT_SECRET = "your-client-secret";

    public static String getAccessToken() throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        String body = "grant_type=client_credentials" +
            "&client_id=" + URLEncoder.encode(CLIENT_ID, StandardCharsets.UTF_8) +
            "&client_secret=" + URLEncoder.encode(CLIENT_SECRET, StandardCharsets.UTF_8);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(TOKEN_ENDPOINT))
            .header("Content-Type", "application/x-www-form-urlencoded")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        // Parse JSON to extract access_token
        // Using a JSON library like Jackson or Gson recommended
        
        return response.body(); // Extract access_token from JSON
    }
}

Token Response

The token endpoint returns a JSON response containing your access token:

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

• access_token - The bearer token to use in API requests (this is a JSON Web Token, or JWT)
• token_type - Always "Bearer"
• expires_in - Token lifetime in seconds (typically 3600 = 1 hour)

Using the Access Token

Once you have an access token, include it in the Authorization header of all API requests using the Bearer authentication scheme:

JavaScript

const axios = require("axios");

const BASE_URL = "https://preprod.accuris.io";
const ACCESS_TOKEN = "your-access-token";

async function makeAuthenticatedRequest() {
  const response = await axios.get(`${BASE_URL}/industrial/document/standard`, {
    headers: {
      Authorization: `Bearer ${ACCESS_TOKEN}`,
    },
  });

  return response.data;
}

C#

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

public class ApiRequestExample
{
    private static readonly string BaseUrl = "https://preprod.accuris.io";
    private static readonly string AccessToken = "your-access-token";

    public static async Task MakeAuthenticatedRequest()
    {
        using var client = new HttpClient();
        
        client.DefaultRequestHeaders.Authorization = 
            new AuthenticationHeaderValue("Bearer", AccessToken);

        var response = await client.GetAsync(
            $"{BaseUrl}/industrial/document/standard"
        );
        
        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        
        return content;
    }
}

Java

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

public class ApiRequestExample {
    private static final String BASE_URL = "https://preprod.accuris.io";
    private static final String ACCESS_TOKEN = "your-access-token";

    public static String makeAuthenticatedRequest() throws Exception {
        HttpClient client = HttpClient.newHttpClient();
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/industrial/document/standard"))
            .header("Authorization", "Bearer " + ACCESS_TOKEN)
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        
        return response.body();
    }
}

The header format is:

Authorization: Bearer <access_token>

Replace <access_token> with the actual token value received from the token endpoint.

Token Expiration and Renewal

Access tokens expire after the time specified in expires_in (typically 1 hour). When your token expires, API requests will return a 401 Unauthorized response.

To handle expiration:

• Track when your token was issued and when it will expire
• Request a new token before the current one expires
• Implement retry logic to automatically refresh expired tokens

You can request a new token at any time using the same client credentials - there's no refresh token needed with the Client Credentials flow.

Security Best Practices

• Server-side only - Never use client credentials in browser-based or mobile applications. Only use them in secure backend services.
• Secure storage - Store credentials in environment variables, secret management systems, or secure configuration, never in source code.
• HTTPS only - Always use HTTPS for all requests to protect credentials and tokens in transit.
• Token caching - Cache and reuse tokens until they expire instead of requesting a new token for every API call. This improves performance and reduces load.
• Credential rotation - Periodically rotate your credentials as part of your security practices.