API console

The API reference is also an API console. Connect it to your tenant with a personal access token and you can send any operation from the browser, inspect the real response, and copy a ready-made code sample in the language you use.

Open the API referenceEvery Elastio API operation, with Test Request and code samples.

Connect your tenant

The connect bar at the top of the reference holds your tenant and token.

1. Enter your tenant: the subdomain of your console URL. For https://acme.app.elastio.com, enter acme. You can also paste the full URL; the console keeps only the subdomain.
2. Paste a personal access token into the token field. If you paste it with a leading Bearer , the prefix is removed. See Authentication to issue one.
3. Optionally select Remember on this device.
4. Select Connect.

When you connect, the console calls GET /gateway/api/v1/health_check on your tenant and shows the result next to the form, for example Connected to acme.app.elastio.com. It also sets the server for every operation to https://acme.app.elastio.com and fills in the token for authentication.

Where your token is kept

• By default, the tenant and token are kept in this browser tab’s session storage. They are gone when you close the tab.
• With Remember on this device, they are kept in the browser’s local storage and restored the next time you open the reference on this device. Only use this on a device you trust.
• Clear removes the tenant and token from both session and local storage and disconnects the console.

The portal never stores your token on its servers.

Tip

Use a token with only read grants while you explore. You can issue a separate, short-lived token for the console and revoke it when you are done.

Send a request

1. Find the operation in the sidebar of the reference, or use search.
2. Select Test Request.
3. Fill in path parameters, query parameters and, for write operations, the request body. The reference shows each parameter’s type, allowed values and description from the OpenAPI document.
4. Send the request and inspect the status, headers and body of the response.

Caution

The console talks to your live tenant. POST, PUT, PATCH and DELETE operations create, change and delete real data, such as policies, alerts, tokens and users. Read the operation description before you send a write.

How requests reach your tenant

Your tenant does not accept cross-origin requests from arbitrary websites, so the console does not call it directly. Each request goes to the portal’s relay at /console-proxy, which forwards it to your tenant and returns the response unchanged. The relay:

• Only forwards to HTTPS hosts under elastio.com or elastio.us, on the default port. Any other target is refused.
• Forwards only the headers an API call needs: Accept, Accept-Language, Authorization, Content-Type, If-Match, If-None-Match and Idempotency-Key.
• Strips cookies in both directions. Browser cookies are never sent to your tenant, and Set-Cookie from the tenant never reaches your browser.
• Does not log credentials.
• Accepts request bodies up to 5 MB and waits up to 60 seconds for your tenant to answer.

Responses from the relay carry an x-elastio-console-proxy: 1 header.

Scripts and integrations should call https://{tenant}.app.elastio.com directly. The relay exists only for the browser console.

Code samples

Each operation in the reference shows a code sample for the request you have built, including your parameters and body. cURL is the default; you can switch to other languages and HTTP clients, including Python, PowerShell, JavaScript, Node.js, Go, Java, C# and PHP. Copy the sample and replace the token with a reference to your secret, such as $ELASTIO_TOKEN.

Download the OpenAPI document

The reference is generated from the published OpenAPI document. Download it from the reference, or fetch it directly at /openapi/elastio-api.json, to generate a client or import the API into another tool.

Troubleshooting

What you see	What it means	What to do
rejected the token (401) on connect, or 401 on a request	The token is missing, mistyped, expired or revoked.	Paste the token again, or issue a new one. Check its expires_at.
The token was accepted but lacks access (403), or 403 on a request	The token is valid but its grants do not cover this operation, or the operation needs a tenant admin.	Add the needed scope category or write access to the token, or use an admin’s token. See Scopes.
403 with "error": "Console proxy error"	The relay refused the target host because it is not an Elastio tenant.	Check the tenant you entered and the server URL of the operation.
400 with "error": "Console proxy error"	The target URL is not a valid HTTPS URL on the default port, or contains credentials.	Check the server URL.
413 from the relay	The request body is larger than 5 MB.	Send large requests from your own code instead.
502 from the relay	The relay could not reach your tenant.	Check the tenant name, and try again.
504 from the relay	Your tenant did not answer within 60 seconds.	Narrow the request (filters, smaller page size) or send it from your own code.
answered HTTP …. Check the tenant name. on connect	The health check returned an unexpected status, often because the tenant name is wrong.	Check the spelling of the tenant.
The console relay is unreachable	Your browser could not reach the portal’s relay.	Check your network, VPN or proxy, and reload the page.

Relay errors use their own JSON body, so you can tell them apart from errors returned by your tenant:

{
  "status": 403,
  "error": "Console proxy error",
  "message": "The console can only call Elastio tenants (.elastio.com, .elastio.us). Check the tenant in the server URL."
}

For error responses from the API itself, see Errors.