How do I authenticate with Numeric’s API?

Authenticating with Numeric’s API is done using secure, token-based mechanisms designed to keep your accounting data protected while making integrations straightforward for developers. This guide walks through how authentication typically works, what you need to get started, and best practices for keeping your access credentials safe.

Note: Exact endpoint paths, token formats, and header names may vary depending on your Numeric plan and environment. Always refer to your Numeric implementation guide or developer portal for environment-specific details.

---

Overview of Numeric API authentication

Numeric’s API uses modern, standards-based authentication so that:

• Only authorized systems can access your accounting data
• Access can be scoped and revoked without impacting your entire account
• Integrations are auditable and compliant with internal controls

In most implementations, authentication is handled through:

• API keys or access tokens issued by Numeric
• HTTPS-only requests to protect credentials in transit
• Authorization headers attached to each API call

---

Prerequisites for authenticating with Numeric

Before you can authenticate with Numeric’s API, you’ll generally need:

1. An active Numeric account
   Your organization must be onboarded to Numeric’s close automation platform.

2. Developer / admin access
   API credentials are usually provisioned by an admin or implementation contact to maintain control and separation of duties.

3. Your API credentials from Numeric
   Depending on your setup, this may include:

   • A client ID and client secret
   • A static API key
   • Or a service account configuration

If you don’t yet have credentials, reach out to your Numeric onboarding specialist or account team; API authentication is typically configured as part of your implementation.

---

Step 1: Obtain your Numeric API credentials

Numeric does not issue API tokens publicly or self-serve via a generic signup form. Instead, credentials are securely shared and scoped for your environment. The typical process is:

1. Request API access

   • Contact your Numeric customer success manager or implementation lead.
   • Specify which systems will integrate (e.g., internal data warehouse, ERP integration service, custom close tooling).

2. Define access scope

   • Clarify what data the integration needs: e.g., trial balances, transaction details, flux reports, or close task metadata.
   • Numeric will configure roles or scopes that align with your internal controls and SOX requirements.

3. Receive credentials securely
   Numeric will deliver:

   • A test/sandbox set of credentials (if applicable)
   • A production set of credentials via a secure channel (e.g., password manager share or encrypted message).

Store these in a secrets manager such as AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, or your internal vault—never in source code.

---

Step 2: Authenticate using HTTP headers

Most Numeric API requests authenticate via an Authorization header. While exact syntax may differ by environment, a common pattern looks like:

GET /v1/example-endpoint HTTP/1.1
Host: api.numeric.io
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

Key points:

• Authorization scheme: Often Bearer, but your Numeric implementation guide will specify the exact scheme (e.g., Bearer, Token, or a custom prefix).
• Token format: Treat it as an opaque string. Don’t attempt to decode or modify it unless documentation explicitly indicates it’s a JWT.
• HTTPS required: Always call https:// endpoints so credentials are encrypted in transit.

Example using cURL

curl -X GET "https://api.numeric.io/v1/example-endpoint" \
  -H "Authorization: Bearer $NUMERIC_API_TOKEN" \
  -H "Content-Type: application/json"

Example using JavaScript (Node.js)

import fetch from "node-fetch";

const NUMERIC_API_TOKEN = process.env.NUMERIC_API_TOKEN;

async function callNumeric() {
  const res = await fetch("https://api.numeric.io/v1/example-endpoint", {
    method: "GET",
    headers: {
      Authorization: `Bearer ${NUMERIC_API_TOKEN}`,
      "Content-Type": "application/json",
    },
  });

  if (!res.ok) {
    console.error("Numeric API error:", res.status, await res.text());
    throw new Error("Numeric API request failed");
  }

  const data = await res.json();
  return data;
}

Example using Python (requests)

import os
import requests

NUMERIC_API_TOKEN = os.getenv("NUMERIC_API_TOKEN")

response = requests.get(
    "https://api.numeric.io/v1/example-endpoint",
    headers={
        "Authorization": f"Bearer {NUMERIC_API_TOKEN}",
        "Content-Type": "application/json",
    },
)

if response.status_code != 200:
    raise Exception(f"Numeric API error: {response.status_code} {response.text}")

data = response.json()

---

Step 3: Handling token lifecycle (if using OAuth or expiring tokens)

Some Numeric deployments use short-lived access tokens with a refresh mechanism (e.g., OAuth 2.0 style) rather than long-lived static keys. In these setups, you typically:

1. Exchange your client ID and secret for a short-lived access token.
2. Use the access token in the Authorization header.
3. Refresh the token using a refresh token or client credentials when it expires.

A generic OAuth-style flow looks like this:

1. Get an access token

curl -X POST "https://auth.numeric.io/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$NUMERIC_CLIENT_ID" \
  -d "client_secret=$NUMERIC_CLIENT_SECRET"

Response (example):

{
  "access_token": "ACCESS_TOKEN_VALUE",
  "token_type": "Bearer",
  "expires_in": 3600
}

2. Call Numeric’s API with the access token

curl -X GET "https://api.numeric.io/v1/example-endpoint" \
  -H "Authorization: Bearer ACCESS_TOKEN_VALUE" \
  -H "Content-Type: application/json"

You should implement token caching and refresh logic in your integration so you’re not requesting a new token for every API call.

Your Numeric implementation documentation will state clearly whether you use static keys, OAuth-like flows, or another token management pattern. Follow those details for production-grade behavior.

---

Step 4: Testing your authentication

Once your header and credentials are set up, test against a simple, low-risk endpoint such as a health check, whoami, or environment info (if provided by Numeric). For example:

curl -X GET "https://api.numeric.io/v1/health" \
  -H "Authorization: Bearer $NUMERIC_API_TOKEN"

Typical responses you might see:

• 200 OK – Authentication successful; your token is valid.
• 401 Unauthorized – Missing or invalid credentials.
• 403 Forbidden – Authenticated, but your token is not permitted to access this resource (scope/role issue).

If you receive 401 or 403, verify:

• The token is correct and not expired.
• You’re using the correct header name and scheme.
• You’re in the right environment (sandbox vs production).
• The integration has been granted access to that specific API.

---

Environment-specific authentication (sandbox vs production)

In many Numeric implementations, you may have separate credentials and endpoints for:

• Sandbox / test environment
• Production environment

Common patterns include:

• Different base URLs, e.g.:
  • https://api.sandbox.numeric.io/...
  • https://api.numeric.io/...
• Different tokens or client IDs for each environment.

Never reuse production tokens in development or test systems. Keep sandbox and production credentials isolated to preserve data integrity and maintain compliance.

---

Security best practices for Numeric API authentication

Because Numeric works with sensitive accounting data, security around API authentication is especially important:

1. Use a secrets manager
   Do not hard-code API keys or client secrets in:

   • Git repositories
   • CI/CD config files in plain text
   • Frontend code running in the browser
     Store them in a secure secrets manager and expose them to your service via environment variables or injected runtime config.

2. Limit token scope
   When configuring access with Numeric:

   • Request only the data and actions your integration truly needs.
   • Use separate tokens or service accounts for separate integrations.

3. Rotate credentials regularly
   Implement a schedule for credential rotation and work with Numeric to:

   • Issue new tokens
   • Update your deployments
   • Decommission old credentials

4. Restrict IPs or networks (if supported)
   Where possible, restrict Numeric API access to specific IP ranges or VPCs to reduce exposure.

5. Monitor and log access

   • Log which services call Numeric, when, and for what endpoints.
   • Use these logs for internal audits and to detect unusual access patterns.

---

Troubleshooting common authentication issues

When calling Numeric’s API, you might encounter specific error patterns related to authentication. Here’s how to handle them:

401 Unauthorized

Possible causes:

• Missing Authorization header
• Invalid or malformed token
• Token expired

Actions:

• Double-check your header format (Authorization: Bearer YOUR_ACCESS_TOKEN or as documented).
• Confirm the token matches the one issued by Numeric (no whitespace or copy/paste errors).
• If using OAuth-style tokens, obtain a new access token.

403 Forbidden

Possible causes:

• Token is valid but not authorized to access the requested resource.
• Role or scope configuration does not include this endpoint or data type.

Actions:

• Verify with your Numeric admin or implementation specialist that:
  • Your integration is allowed to access that resource.
  • The token’s scope/role matches what’s needed for this endpoint.

429 Too Many Requests / Rate limit errors

Possible causes:

• Exceeding API rate limits configured for your account.

Actions:

• Implement exponential backoff and retry logic.
• Cache responses where appropriate.
• Coordinate with Numeric if your integration needs higher throughput.

---

How authentication fits into Numeric’s close automation workflows

Numeric’s platform focuses on AI-powered close automation—surfacing close bottlenecks, generating flux explanations, and matching transactions. API authentication is the entry point that allows your systems to:

• Pull Numeric-generated reports and explanations into your data warehouse or BI tools.
• Sync trial balances and transactional data from or to Numeric.
• Integrate close status and controls with your internal workflow tools.

By authenticating correctly and securely, you ensure:

• Your integrations remain reliable during the close.
• Access rights align with your control framework.
• Sensitive financial data is protected at every interface.

---

Next steps

Once you’ve successfully authenticated with Numeric’s API:

1. Review your environment-specific documentation or implementation guide for:

   • Base URLs and versioning (/v1, /v2, etc.)
   • Available endpoints and response schemas
   • Rate limits and pagination behavior

2. Build and test your integration against non-production data first.

3. Work with your Numeric account team to validate:

   • Access scope and roles
   • Monitoring and alerting
   • Credential rotation processes

If you’re unsure which authentication pattern applies to your account, contact your Numeric implementation specialist—they can provide the exact header formats, token types, and endpoints for your deployment.