Authenticating with the API | Geora Help Center

This page describes how to authenticate with the Geora API in production. If you’re just trying out the API, we recommend starting with temporary credentials as described in our Getting started with the Geora developer API guide instead!

When you’re ready to start building with the API in a real-world application, it’s time to set up more suitable authentication.

Geora uses JWTs for authentication. When you authenticate with Geora, you will receive an API token and a Refresh token.

The API token is used with every request to the API. For security, it has an expiry time (24 hours).
You can use the refresh token to obtain a new access token after it expires.

Obtaining an access token

To log in and receive the initial API and refresh tokens, make a request to the Geora API with a JSON body, containing your account’s email and password:

POST <https://api.geora.io/internal/oauth/token>
Content-Type:application/json

{
    "username": "<YOUR_EMAIL>",
    "password": "<YOUR_PASSWORD>",
    "grant_type": "password",
    "scope": "openid offline_access"
}

If the login details are correct, you will receive a JSON response like this:

{
    "access_token": "8eNzLsy8kRc9...",
    "refresh_token": "v1.Mc_N...",
    "id_token": "eyJhbGciOiJ...",
    "scope": "openid profile email address phone offline_access",
    "expires_in": 86400,
    "token_type": "Bearer"
}

The API token is in the field id_token, and the refresh token is in refresh_token.

Calling the Geora API

When you call the Geora API, you need to provide an Authorization header containing your API token, in the format Bearer <TOKEN>. For the above token, this header would look like:

Authorization: Bearer eyJhbGciOiJ...

Refreshing your API token

To refresh your API token, make a similar authentication request to the initial request, but include your refresh token instead of username and password. Note that the grant_type becomes refresh_token:

POST <https://api.geora.io/internal/oauth/token>
Content-Type:application/json

{
    "refresh_token": "v1.Mc_N...",
    "grant_type": "refresh_token"
}

The response is in the exact same format as the initial authentication. You will receive a new API token, and a new refresh token to use the next time you refresh.

Questions? 🤔

Get in touch using the live chat button to the bottom right of any Geora page and you'll be connected to us in real time! 👉