HTTP request setup guide

Building blocks: send and receive requests, read the web and other everyday tools.

To put HTTP request to work after connecting it, see Intake: webhooks, watched endpoints and rules.

Ways to connect

Company admins connect apps, on the Integrations page in Everdeck: open HTTP request, choose one of the ways below, follow its steps and fill in its fields. Everdeck checks what you enter before it saves anything, and asks you to confirm it’s you (your second factor) before you type any secret. How connecting works.

HTTP request can be connected 7 ways. Where there’s a key or token to paste, that’s usually the quickest.

Bearer token

Token.

1. In the app agents should call, create an API token with only the access they need (read-only if they only read).
2. Enter the API's base URL, for example https://api.example.com/v1, and paste the token. Every request sends Authorization: Bearer <token>.
3. Optionally list the paths agents may call, headers every request needs, and a cheap GET path (for example /me) to test the connection.

Field	What to enter
Base URL	Web address. For example https://api.example.com/v1. Agents can only call paths under this URL. Use https; only public hosts on ports 443 and 80 can be reached.
Token	A secret: Everdeck saves it encrypted and never shows it again.
Allowed paths (optional, one prefix per line)	Text. For example /orders /customers.
Headers for every request (optional JSON object, not for secrets)	Text. For example {"Accept": "application/json"}.
Path to test the connection with a GET (optional)	Text. For example /me.

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at the API you connected until you delete or rotate it there.

API key in a header

API key.

1. In the app agents should call, create an API key with only the access they need.
2. Enter the API's base URL, the header the API reads the key from, and the key itself.
3. Optionally list the paths agents may call and a cheap GET path to test the connection.

Field	What to enter
Base URL	Web address. For example https://api.example.com/v1. Agents can only call paths under this URL. Use https; only public hosts on ports 443 and 80 can be reached.
Header name (optional)	Text. Starts as X-API-Key. For example X-API-Key, Api-Key or Authorization.
Header value	A secret: Everdeck saves it encrypted and never shows it again. The key, with any prefix the API expects (for example Token abc123).
Allowed paths (optional, one prefix per line)	Text. For example /orders /customers.
Headers for every request (optional JSON object, not for secrets)	Text. For example {"Accept": "application/json"}.
Path to test the connection with a GET (optional)	Text. For example /me.

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at the API you connected until you delete or rotate it there.

API key in the query string

API key.

1. Create an API key in the app agents should call. Prefer a header method if the API offers one: keys in URLs end up in server logs.
2. Enter the API's base URL, the query parameter that carries the key, and the key.

Field	What to enter
Base URL	Web address. For example https://api.example.com/v1. Agents can only call paths under this URL. Use https; only public hosts on ports 443 and 80 can be reached.
Query parameter name (optional)	Text. Starts as api_key.
API key	A secret: Everdeck saves it encrypted and never shows it again.
Allowed paths (optional, one prefix per line)	Text. For example /orders /customers.
Headers for every request (optional JSON object, not for secrets)	Text. For example {"Accept": "application/json"}.
Path to test the connection with a GET (optional)	Text. For example /me.

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at the API you connected until you delete or rotate it there.

Username and password (HTTP Basic)

Username and password.

1. Use a dedicated API user (or the username and API password the app issues for integrations), with only the access agents need.
2. Enter the API's base URL, the username and the password.

Field	What to enter
Base URL	Web address. For example https://api.example.com/v1. Agents can only call paths under this URL. Use https; only public hosts on ports 443 and 80 can be reached.
Username	Text.
Password	A secret: Everdeck saves it encrypted and never shows it again.
Allowed paths (optional, one prefix per line)	Text. For example /orders /customers.
Headers for every request (optional JSON object, not for secrets)	Text. For example {"Accept": "application/json"}.
Path to test the connection with a GET (optional)	Text. For example /me.

Disconnecting deletes the credentials Everdeck saved, but Everdeck can't revoke them: the key, token or password itself keeps working at the API you connected until you delete or rotate it there.

OAuth 2.0 client credentials (no sign-in)

Your OAuth app.

This way uses the client ID and secret of an OAuth app you create for the API you connected. There’s no sign-in page: Everdeck asks the API you connected for a token with them.

Its OAuth app belongs to one company and is tied to the token endpoint it was registered for: Everdeck sends the app’s secret only there.

1. In the provider's console, create a machine-to-machine (confidential) client allowed to use the client credentials grant, with only the scopes agents need.
2. Enter the API's base URL, the token endpoint, the scopes (and audience, if the provider asks for one), then the client ID and secret.
3. Everdeck fetches tokens when needed and sends them as Authorization: Bearer <token>.

Field	What to enter
Base URL	Web address. For example https://api.example.com/v1. Agents can only call paths under this URL. Use https; only public hosts on ports 443 and 80 can be reached.
Token endpoint	Web address. For example https://auth.example.com/oauth/token.
Scopes (optional, separated by spaces)	Text.
Audience (optional; Auth0 and some others need it)	Text.
Allowed paths (optional, one prefix per line)	Text. For example /orders /customers.
Headers for every request (optional JSON object, not for secrets)	Text. For example {"Accept": "application/json"}.
Path to test the connection with a GET (optional)	Text. For example /me.

Disconnecting deletes the access token Everdeck saved for this connection. The OAuth app's client ID and secret stay saved under OAuth apps in Everdeck and keep working at the API you connected until you delete the app or rotate its secret there.

OAuth 2.0 with your own app (sign in)

Your OAuth app.

This way signs in with an OAuth app you create for the API you connected, as its steps describe: Everdeck never uses an app of its own. Register this redirect URI with your app:

https://everdeck.io/api/oauth/callback

Then save the app’s client ID and secret in Everdeck, on the connect page or under OAuth apps, and sign in.

Its OAuth app belongs to one company and is tied to the token endpoint it was registered for: Everdeck sends the app’s secret only there.

1. In the provider's developer console, register an OAuth app (a confidential web client using the authorization code grant) and add the redirect URI https://everdeck.io/api/oauth/callback.
2. Enter the API's base URL, the provider's authorization and token endpoints and the scopes agents need, then the app's client ID and secret. If the provider has a token revocation endpoint, enter it too, so disconnecting ends the sign-in there.
3. Click Connect and sign in as the account agents should act as.

Field	What to enter
Base URL	Web address. For example https://api.example.com/v1. Agents can only call paths under this URL. Use https; only public hosts on ports 443 and 80 can be reached.
Authorization endpoint	Web address. For example https://auth.example.com/oauth/authorize.
Token endpoint	Web address. For example https://auth.example.com/oauth/token.
Revocation endpoint (optional)	Web address. For example https://auth.example.com/oauth/revoke. Where Everdeck ends the sign-in when you disconnect (RFC 7009 token revocation). It must be on the token endpoint's origin (the same https host and port). Leave it empty if the provider has none.
Scopes (separated by spaces) (optional)	Text. Include the provider's scope for refresh tokens (often offline_access) so the connection keeps working.
Allowed paths (optional, one prefix per line)	Text. For example /orders /customers.
Headers for every request (optional JSON object, not for secrets)	Text. For example {"Accept": "application/json"}.
Path to test the connection with a GET (optional)	Text. For example /me.

When you disconnect, Everdeck asks the API you connected to revoke the sign-in, but only if you filled in the Revocation endpoint field. Either way it then deletes the tokens it saved. Without that field nothing is revoked: end the access in the provider's own settings.

No authentication

No sign-in.

1. Use this only for public APIs. For anything that needs a key or token, pick another method so the secret is sealed.
2. Enter the API's base URL and, optionally, the paths agents may call.

Field	What to enter
Base URL	Web address. For example https://api.example.com/v1. Agents can only call paths under this URL. Only public hosts on ports 443 and 80 can be reached.
Allowed paths (optional, one prefix per line)	Text. For example /public.
Headers for every request (optional JSON object, not for secrets)	Text. For example {"Accept": "application/json"}.
Path to test the connection with a GET (optional)	Text.

Disconnecting deletes the settings Everdeck saved for this connection. There's nothing to revoke: this way doesn't use a key, token or sign-in.

What agents can do

An agent uses an action only when its charter grants it, on the agent’s Tools tab, where you choose whether each one runs by itself (Auto), asks first or never runs. Each action has a risk tier: tier 3 actions, which customers or the public see, ask first unless you choose otherwise, and tier 4 actions (money, deleting things, access) always need a person. How tools and tiers work.

Actions marked Reads outside content return things people outside your company may have written. Agents treat what they read as information, never as instructions, and their riskier actions later in the same session need approval.

• GET requestTier 0 · ReadReads outside contenthttp_request_get

  Read from the API: send a GET to a path under the connection's base URL. Returns the status code, key response headers (content type, location, link, rate limits) and the body: JSON parsed, text trimmed, files saved to the company's files.

• POST requestTier 3 · ExternalReads outside contenthttp_request_post

  Create something or trigger an action: send a POST with a JSON, form, text or file body. Returns the status, key headers and the response body. Use at most one of json, form or text.

• PUT requestTier 3 · ExternalReads outside contenthttp_request_put

  Replace a resource: send a PUT with a JSON, form, text or file body. Returns the status, key headers and the response body.

• PATCH requestTier 3 · ExternalReads outside contenthttp_request_patch

  Change some fields of a resource: send a PATCH, usually with a JSON body. Returns the status, key headers and the response body.

• DELETE requestTier 4 · Money or irreversibleReads outside contenthttp_request_delete

  Delete a resource with a DELETE request. Returns the status and the response body, if any.

What can start work

These events from the API you connected can become tasks for your agents through Intake. How Intake works.

A GET endpoint you choose (for example /orders?status=new) returned an item that wasn't there before.

Connect the HTTP request connector first. Then, on the Intake page, open Webhooks and sources and select Watch an API endpoint: choose the connection, the path to check, where the list is in the answer and the field that identifies each item. Then, on the Rules tab, select New rule to say which requests become tasks and who gets them.

Testing, problems and disconnecting

Everdeck checks the connection when you save it. On the connection’s page in Integrations, Test checks it again at any time.

If the API you connected later refuses the connection, for example because a key was deleted or a sign-in expired, the connection shows Needs attention on the Integrations page and the people who manage connections are told. Agents can’t use it until a company admin fixes it with Edit or Reconnect.

To stop agents using HTTP request, open the connection and select Disconnect. Agents stop using it at once and its saved credentials are deleted. What else happens depends on how it was connected: each way above says.