Skip to main content

Authentication

Application APIs and data can be accessed with a secure token. Tokens can be JWT tokens created from a provider such as Auth0.com 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 https://account.codehooks.io

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 https://myproject-ff00.api.codehooks.io/dev/myapi \
-H 'x-apikey: 5f1ce782-5798-4295-bdd0-51568390a59c'
note

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 https://account.codehooks.io, find the project and the space settings to add a new token.

add API token using web

Authenticate users with JWT (using JWKS)​

Set up JWKS with the CLI​

If you have set up JWT authentication using Auth0.com (Okta), Clerk 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://<YOUR_AUTH0_TENANT>.auth0.com/.well-known/jwks.json
Set JWKS url to space 'dev'
Auth providerJWKS URL
Auth0.comhttps://<YOUR_AUTH0_TENANT>.auth0.com/.well-known/jwks.json
Clerk.comhttps://<YOUR_CLERK_DOMAIN>/.well-known/jwks.json

Using the web application to set a JWKS endpoint​

In your account at https://account.codehooks.io, find the project and the space settings to set the JWKS endpoint URL.

set JWKS endpoint using web

tip

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 11.22.33.44.

headers: {
    host: 'myapp-f0gt.api.codehooks.io',
    'x-request-id': 'ba5582e3bafd12602b3f70a5af5ab20f',
    'x-real-ip': '11.22.33.44',
    'x-forwarded-for': '11.22.33.44',
    'x-forwarded-host': 'myapp-f0gt.api.codehooks.io',
    'x-forwarded-port': '443',
    'x-forwarded-proto': 'https',
    'x-forwarded-scheme': 'https',
    'x-scheme': 'https',
    accept: '*/*',
    'user-agent': 'Thunder Client (https://www.thunderclient.com)',
    '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 11.22.33.44

You can use a authentication hook to intercept API requests.