Skip to content

General

Using the public API

Authentication

Info

You need to receive required access tokens and identity information before using any other public API endpoints!

All the public API endpoint requests (as well as subscribing to real-time channels via Socket API) require an access token, as described in the Authorization section. You also need to determine the unique ID for the visitor.

Authenticate a new visitor

An example request

1
POST https://service.giosg.com/api/v5/public/orgs/e6a08f51-c250-4074-847b-58d444dbbeb1/auth

1
2
3
{
  "visitor_secret_id": null
}

An example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "visitor_id": "8a60b202474547dbb8ce19737e4c166f",
  "visitor_secret_id": "2bc12b9cb90d4faf92141c45d560164584ad030d78cb06f91e",
  "organization_id": "e6a08f51-c250-4074-847b-58d444dbbeb1",
  "socket_url": "https://messagerouter.giosg.com/003/2/router",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.we2snuuhq-cnPk-GMJVoBhyZ7ZKPa95Qxe_3VkEaf_E",
  "expires_at": "2015-12-22T11:25:30.595Z",
  "expires_in": 1800,
  "minimal_bar_version": 3
}

When a new visitor starts using the public API endpoints, you need retrieve the required identity and access token by making the following request:

POST /api/v5/public/orgs/<organization_id>/auth

You need to accept a JSON response with HTTP request headers.

The <organization_id> must be the UUID of your organization account. You can get this on your giosg account settings.

When authenticating a new user, the payload may be an object with attribute(s) visitor_secret_id with value null. You may even omit these attributes and POST just an empty payload object.

The response is an object with the following attributes:

Attribute Type Description
visitor_id string Your organization-specific public identifier. It is specific only to the context of the related organization (<organization_id>). For other organizations, you should make another request. This identifier can be sent to anyone.
visitor_secret_id string Your secret identifier. You should store this to a local storage! Do not share this secret to anyone! Otherwise anyone can access your information or impersonate you.
organization_id UUID ID of the organization to which this information is specific.
socket_url string URL to which any socket connection should be made if you want to subscribe to real-time channels.
access_token string The access token that you need to use to authorize access to any other public HTTP API endpoints or real-time channels.
expires_at datetime When this information (especially the access token) expires. You should renew this information before it expires.
expires_in integer After how many seconds this information (especially the access token) expires. You should renew this information before it expires. Useful for scheduling a timer for renewing the authentication.
minimal_bar_version integer nternally used field. Don't use it.

Warning

You usually only need your visitor_secret_id when renewing your authentication. You should persist it for later use. Do not share the secret ID with anyone!

In addition to the visitor_secret_id, you may also temporarily persist other information, such as your visitor_id and access_token. This may be useful e.g. for faster application startup. However, only store the most recent information received from the server.

Authenticate a returning visitor

An example request

1
POST https://service.giosg.com/api/v5/public/orgs/e6a08f51-c250-4074-847b-58d444dbbeb1/auth

1
2
3
{
  "visitor_secret_id": "a112586d51354fcbbcb9d55daee36e76"
}

An example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "visitor_id": "8a60b202474547dbb8ce19737e4c166f",
  "visitor_secret_id": "a112586d51354fcbbcb9d55daee36e76",
  "organization_id": "e6a08f51-c250-4074-847b-58d444dbbeb1",
  "socket_url": "https://messagerouter.giosg.com/004/1/router",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.LwimMJA3puF3ioGeS-tfczR3370GXBZMIL-bdpu4hOU",
  "expires_at": "2015-12-22T15:03:12.901Z",
  "expires_in": 1800,
  "minimal_bar_version": 3
}

After the very first authentication as a new visitor, you usually want to renew your authentication. For example:

  • You are relaunching your client app
  • Your access token is about to expire (or already expired)
  • You want to authorize to another organization as a same unique visitor

Re-authentication is done to the same endpoint than the first authentication:

POST /api/v5/public/orgs/<organization_id>/auth

However, you should send your visitor_secret_id stored to your client, as an attribute of the payload object.

The response is similar than when authenticating as a new visitor. You should again persist the returned visitor_secret_id, an optionally other information.

Notice

In practice, whenever you re-authenticate with your secret ID, you always receive the same visitor_id. You also receive back the same visitor_secret_id that you POSTed. However, this will not be guaranteed in the future, and you should always store the most recent information received in the response!

Authorization

An example HTTP request header

1
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.LwimMJA3puF3ioGeS-tfczR3370GXBZMIL-bdpu4hOU

You need to provide a valid access token on your Authorization HTTP header for all the public API requests (except when authenticating).

Authorization: Bearer <access_token>

Notice

Replace the &lt;access_token&gt; with the most recent access token you received when authenticated as a visitor.