Connect an API that isn't listed

If the API you need isn’t in the supported services list, connect it with one of six generic services: HTTP Bearer Token, HTTP Basic Authentication, Custom Token Authentication, HTTP OAuth 1.0a, HTTP HMAC signature, or HTTP AWS Signature v4. You enter the credential once in the dashboard, and your function calls the API with ctx.http.authed('alias') like any other connected service. The platform adds the credential to the request, so the secret never reaches your code.

This page walks through the whole path with a made-up credential against a public test API, so you can run it without a third-party account.

Pick a generic service

OAuth 2.0 with token refresh is not a generic service. If the service offers OAuth 2.0, use its own entry in the supported services list, which handles sign-in and refresh for you.

What to enter in the form

For Custom Token Authentication:

Signed requests

OAuth 1.0a, HMAC, and AWS Signature v4 sign each request instead of sending a fixed token. You enter the secrets once, and the platform computes the signature on every call.

Pin to domain is required

A signed credential can only be used against the domain you pin it to, and its subdomains. api.vendor.com allows eu.api.vendor.com, not vendor.com. A request to any other host fails instead of sending the credential. Enter the bare domain: no https://, path, wildcard, or port.

These services also refuse to send a request when a required value is missing.

HTTP OAuth 1.0a

You supply the credentials. Helix signs each request with them but doesn’t run the OAuth 1.0a token exchange, so for an API that needs a user’s access token you must already hold the token and token secret.

Not supported:

• The realm parameter
• The RSA-SHA1 and PLAINTEXT signature methods
• Requests with a form-urlencoded body

HTTP HMAC signature

The signature covers the exact bytes your function sends. If the API verifies a re-serialized version of the body, the signatures won’t match. Sign the body, or list at least one signed header.

HTTP AWS Signature v4

The region and service come from a regional host such as sts.us-east-1.amazonaws.com. Set them yourself when the host doesn’t name them, or names a different service than the one that signs. For example, bedrock-runtime signs as bedrock.

Worked example

This example uses httpbin.org, a public API that echoes back what it receives. The token below is made up. Don’t enter a real secret while you try this.

1. Create the authentication

helix auth connect --new

The command opens the dashboard’s connect page for your workspace. Add --no-open to print the link instead. In the dashboard, choose HTTP Bearer Token, enter demo-token-123 as the token, and name the authentication.

Back in the terminal, the CLI finds the new authentication and writes an alias into helix.config.ts. The CLI suggests an alias from the service name, so here it is http_bearer_token. You can type a different one at the prompt, using lowercase letters, digits, and underscores, starting with a letter. Without a terminal, such as in an agent loop, the command only prints the link. Once you’ve created the authentication, wire it up with helix auth connect or helix auth add <alias> <uuid>.

2. Call the API

// functions/api/v1/demo.get.ts
import { defineFunction } from '@trayai/helix-sdk';

export default defineFunction(async (ctx) => {
  const res = await ctx.http
    .authed('http_bearer_token')
    .get('https://httpbin.org/bearer');

  return res.body;
});

An authed call returns { status, body, headers }. body is already parsed JSON for a JSON response. A non-2xx answer from the API is returned, not thrown, so check res.status when you need to handle errors.

3. Run it

helix dev
curl http://localhost:3000/api/v1/demo

Success looks like this:

{ "authenticated": true, "token": "demo-token-123" }

The test API received Authorization: Bearer demo-token-123, which your function never wrote.

Try the other two

The same steps work with the other generic services. Change the alias and the URL in step 2, and return res.body as before.

Try the signed services

Each example uses a public test API and made-up or published test keys, so you need no real account. Create the authentication as in step 1 above. The aliases below are the CLI’s suggested defaults (http_oauth1, http_hmac, http_aws_sigv4), and you can edit them at the prompt. Call each from a function that returns the result:

// functions/api/v1/signed.get.ts
import { defineFunction } from '@trayai/helix-sdk';

export default defineFunction(async (ctx) => {
  const res = await ctx.http.authed('http_oauth1').get('https://postman-echo.com/oauth1');
  return { status: res.status, body: res.body };
});

OAuth 1.0a

Postman Echo checks the signature with its published test key.

Call GET https://postman-echo.com/oauth1. Success is status 200 with this body:

{ "status": "pass", "message": "OAuth-1.0a signature verification was successful" }

HMAC signature

Send a JSON body to the echo endpoint:

const res = await ctx.http
  .authed('http_hmac')
  .post('https://httpbin.org/anything', { body: { event: 'order.created', id: 42 } });

The echo shows the exact string sent in body.data and the signature in body.headers['X-Signature']. For this body and secret the signature is eec200cc0004a0c3ceb9aeb1a4ddea237a549f1f65a11c40352347cbfdc394b4. Check it yourself:

printf '%s' '{"event":"order.created","id":42}' | openssl dgst -sha256 -hmac 'dummy-hmac-secret'

AWS Signature v4

These are the example keys from AWS’s own documentation, so AWS rejects them. Call GET https://sts.us-east-1.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15. Success for this exercise is status 403 with <Code>InvalidClientTokenId</Code> in the body. That shows AWS parsed a correctly formed signed request and rejected only the key. An unsigned request returns MissingAuthenticationToken instead. This does not prove the signature is valid, only that it is well formed. With a real key, the same call returns your account details.

Troubleshooting

The API answers 401. The call doesn’t throw: the 401 comes back as res.status === 401. The values or the location are wrong. Check the Token, Location, and Location Value you entered against what the API’s documentation asks for.

You want to see what is sent. Point a made-up credential at an echo endpoint such as https://httpbin.org/anything. Never do this with a real secret, because the echo site would receive it.

A signed request is refused. HTTP OAuth 1.0a, HTTP HMAC signature, and HTTP AWS Signature v4 send nothing when a required value is missing or the host is outside the pinned domain. Check the form values and the Pin to domain against the URL you call.

A missing alias error. The alias isn’t in helix.config.ts. The error lists the aliases that are configured, so compare it with the name your code uses.

For how aliases, refresh, and request logging work, see connected services.