Skip to content

Backend authentication

By default, anyone with the hostname of a backend you spawn can connect to it. If you would like to limit access to a backend to a smaller group of people, you can request that a backend be gated behind basic bearer token authentication.

Note that this refers to requiring bearer tokens for backends you spawn. For authenticating to the API itself, see the authentication section of the API docs.

Requesting a bearer token at spawn time

To use bearer token authentication, you first request that a backend be gated by a bearer token at spawn time. How you do this will depend on whether you are using the jamsocket CLI or the REST API.

  • To request a bearer token for a CLI request, pass -r or --request-bearer-token to the jamsocket spawn command.
  • To request a bearer token for an API request, pass require_bearer_token: true in the request body.

Accessing a backend with a bearer token

There are two ways you can authenticate a request to a backend that has a bearer token: an Authorization header, or a cookie.

Using an Authorization header

If you can add headers to the HTTP request, the recommended way is to use standard HTTP bearer token authentication. Add an Authorization header to the request, containing the value Bearer <bearer_token>, where <bearer_token> is the bearer token that was returned to you when you spawned the backend.

In a fetch request, this would look like:

fetch('https://abcde.jamsocket.run/path/to/some/resource', {
  headers: {
    Authorization: `Bearer ${bearerToken}`,
  },
})

Sometimes, you can’t add headers to the HTTP request. For example, if you want to load the backend directly in a browser. In this case, you can have the browser pass a _plane_auth cookie containing the text of the bearer token. To set this cookie in the browser, you can send them to the special https://<backend_id>.jamsocket.run/_plane_auth URL, which will set the cookie for you. For example:

document.location = `https://abcde.jamsocket.run/_plane_auth?token=${bearerToken}`;

This will set the _plane_auth cookie to the value of bearerToken, and redirect the browser to the backend’s root URL. You can redirect to another relative URL by passing it as the redirect query parameter:

const urlEncodedRedirectUrl = encodeURIComponent('/path/on/backend?query=string&are=fine');
document.location = `https://abcde.jamsocket.run/_plane_auth?token=${bearerToken}&redirect=${urlEncodedRedirectUrl}`;

The path must be relative. Query parameters will also be passed, but ensure that the redirect URL is URL-encoded.