Skip to main content


Application APIs and data can be accessed with a secure token. Tokens can be JWT tokens created from a provider such as or API tokens created by yourself (or any project user with ADMIN rights).

In addition, some CLI commands can use a special admin token (se below).

App-to-app authentication with API tokens

Create an API token with the CLI

API tokens can be created i two ways.

  1. Using the CLI command coho add-token
  2. Using the admin application at

The example below shows how to use the CLI to create a new READ access API token.

coho add-token --readonly
Created new token 5f1ce782-5798-4295-bdd0-51568390a59c with access READ

The API token can now be used to access your application API.

Add the x-apikey as a HTTP header in the request.

curl \
-H 'x-apikey: 5f1ce782-5798-4295-bdd0-51568390a59c'

The secure token should not be used from web pages. We recommend that you only use it server side.

Using the web application to add an API token

In your account at, find the project and the space settings to add a new token.

add API token using web

Authenticate users with JWT (using JWKS)

Setup JWKS with the CLI

If you have set up JWT authentication using or similar services, you can easily set up a JWKS endpoint in the space settings. All API calls will then be verified using this mechanism.

# add JWKS endpoint
$ coho jwks https://<insert tenant name>
Set JWKS url to space 'dev'

Using the web application to set a JWKS endpoint

In your account at, find the project and the space settings to set the JWKS endpoint URL.

set JWKS endpoint using web


You can also roll your own authentication using code. Read more about using using authhooks for this.

Verifying JWT tokens - RS256 vs HS256

By default, to verify login tokens (JWT), Auth0 example applications now use the asymmetric RS256 algorithm instead of the HS256 symmetric one. What is the difference? HS256 requires you to use a secret key to verify the token but RS256 let you use a public key which can be fetched from an URL on the web (JWKS URL). You can read more about it in this blogpost by Auth0.

Use admin tokens to authenticate with the CLI

For use with the CLI, you can create admin tokens instead of having to log in to your account as a user with ADMIN rights. Admin tokens belong to the personal account or a team and applies to the following codehooks CLI commands: deploy, undeploy, createindex, removeindex, backup, restore, import, export, query.

Admin tokens are ideal for use in shell scripts and for CI purposes.

# add admin token
$ coho add-admintoken
? Select personal account or team to add admin token to Personal

New admin token added: 0882e570d8fc7fe97ae958ae8df3d7ba-7f5c5eb7177c

Please copy this now and keep it secret. It will never be shown in full again.
# use the admin token
$ coho deploy --admintoken 0882e570d8fc7fe97ae958ae8df3d7ba-7f5c5eb7177c
Deploying to Project: students-3bfe Space: dev
Deployed Codehook successfully! 🙌

Use IP address to limit API access

From your serverless functions you can inspect the client IP address from the request header fields. The example headers listen below shows that the client IP address is

headers: {
host: '',
'x-request-id': 'ba5582e3bafd12602b3f70a5af5ab20f',
'x-real-ip': '',
'x-forwarded-for': '',
'x-forwarded-host': '',
'x-forwarded-port': '443',
'x-forwarded-proto': 'https',
'x-forwarded-scheme': 'https',
'x-scheme': 'https',
accept: '*/*',
'user-agent': 'Thunder Client (',
'x-api-key': '07ee0bba-xxxx-yyy-zzzz-dfd0b991fa0a'

Use the CLI command coho whitelist or the admin web application to give exclusive IP addresses API access, e.g.

coho whitelist

You can use a authentication hook to intercept API requests.