Skip to content

Get API token

Overview

Requests to Giosg API's can be authenticated either by API token or by OAuth2 Access tokens. This guide describes how you can obtain and use each of them.

User API token is best suited for scripts and backend integration use cases and OAuth2 flow should be used when there is user interface involved.

Prerequisites

Before you can obtain your API token, you should have your Giosg account created and email confirmed.

Obtain User API token

You may create API token in Giosg user interface by logging in to Console → Settings Menu → Company → Access tokens. You can get there by with this link also: https://service.giosg.com/settings/live/company/tokens.

To create API token, give it good description so you know which token is in question if you later on want to revoke (delete) the token. When token is created, store it in some safe place as it cannot be viewed again.

Once you have obtained your API token, define the Authorization HTTP header for your API request to use it.

Example: Authorization: Token <api token>

Remember that the API token is connected to the user that was used to create the token. This means that if the user is deleted also the token is invalidated. Token will also have same permissions as the associated user so you may also limit tokens permissions per use case.

Obtain OAuth2 Access token

Giosg uses an OpenID Connect compatible authentication flow based on OAuth2.

There are two supported authentication flows, as described by OpenID Connect specification:

giosg also supports single sign-on authentication flow:

  • SSO Authentication Flow used by giosg apps to provide authentication to giosg system without user sending credentials.

Using OAuth2 is bit more complex to set up than User API Token authentication so you should checkout this tutorial.

Using authentication tokens

Usage of different tokens is very similar. Both should be placed to Authorization header when making request.

Only subtle difference between User API token and OAuth2 access token usage is the "token word" that you should use in Authorization header. Use Token for User API tokens and Bearer when using OAuth2 access tokens.

Example of User API token usage:

Authorization: Token <api token>

Example of OAuth2 access token usage:

Authorization: Bearer <access token>