ECGrid REST API — Getting Started

The ECGrid REST API is the API-first gateway to the global B2B/EDI network. It exposes mailbox provisioning, trading-partner management, document routing, and real-time interchange tracking through a single JSON-over-HTTPS interface.

This document is a quick-start guide. For the complete, interactive endpoint reference, see Swagger UI.

Base URL

https://rest.ecgrid.io/v2/

All endpoints are versioned under /v2/. This is a production-only API — there is no separate sandbox host.

Authentication

The API supports two authentication methods. Pick whichever fits your integration; both produce identical responses on the rest of the API.

1. API Key

Send your API key in the X-API-Key header on every request. This is the simplest option for server-to-server integrations — no token lifecycle to manage.

X-API-Key: YOUR_API_KEY

2. JWT Bearer Token (with Refresh)

Use this when you need short-lived, user-scoped credentials — for example, interactive sessions or browser-side flows where exposure risk is higher.

Step 1 — Log in to obtain a token pair

POST /v2/auth/login

{  "username": "your.user@example.com",  "password": "YOUR_PASSWORD" }

The response contains an access token (a JWT, used as a Bearer credential on subsequent calls) and a refresh token (used to mint new access tokens without re-prompting for the password).

Step 2 — Call endpoints with the access token

Authorization: Bearer ACCESS_TOKEN

Step 3 — Refresh when the access token expires

POST /v2/auth/refresh

{  "refreshToken": "REFRESH_TOKEN" }

Returns a new access token (and, per rotation policy, a new refresh token). When you receive 401 Unauthorized on a previously-working call, refresh once and retry. If the refresh itself returns 401, the refresh token has expired or been revoked and the user must log in again.

Step 4 — Log out (invalidate the session)

POST /v2/auth/logout

Revokes the current refresh token immediately.

Quick start

Hit GET /v2/users/me to verify your credentials. It returns the account info tied to the API key or token you presented.

cURL

curl https://rest.ecgrid.io/v2/users/me \  -H "X-API-Key: YOUR_API_KEY"

C#

using System.Net.Http; 
using var http = new HttpClient(); http.DefaultRequestHeaders.Add("X-API-Key", "YOUR_API_KEY"); 
var response = await http.GetAsync("https://rest.ecgrid.io/v2/users/me"); response.EnsureSuccessStatusCode(); 
var body = await response.Content.ReadAsStringAsync(); Console.WriteLine(body);

For the same call in Java, Node.js, TypeScript, Python, PHP, and Go, see the live samples on https://rest.ecgrid.io.

Request conventions

• All payloads are JSON. Set Content-Type: application/json and Accept: application/json on any request with a body.
• Strings are UTF-8.
• Timestamps are ISO 8601 UTC (e.g. 2026-04-29T14:30:00Z).

ApiResponse

Successful calls return a standard envelope:

{  "httpStatus": 200,  "message": "",  "traceId": "0HN7K2A1B3C:00000001",  "success": true,  "data": { /* ECGridOS response object or list, depending on the endpoint */ } }

ApiErrorResponse

Failed requests return a non-2xx status code and a standard error envelope:

{  "httpStatus": 404,  "success": false,  "message": "No user found with the supplied ID.",  "detail": "The user ID may not exist or may not be accessible under your session.",  "traceId": "0HN7K2A1B3C:00000001",  "errorInfo": null }

HTTP status codes

Rate limits

• Authenticated endpoints — 180 requests per minute per API key (or per JWT).
• Unauthenticated endpoints (/auth/login, /auth/version) — 40 requests per minute per source IP.

Every response advertises your current usage via X-RateLimit-* headers (limit, remaining, reset). Exceeded calls return HTTP 429 Too Many Requests with a Retry-After header (seconds until the next allowed call).

Treat 429 as a normal, expected response and implement exponential backoff in your client. (Standard practice — same approach used by Stripe, GitHub, and most major REST APIs.)

Higher quotas are available for partners — contact us to request a custom limit.

Full API reference

Every endpoint, request schema, and enumeration is documented and live-callable in Swagger UI.