Esri's Geotrigger Service is replacing Geoloqi! Learn More | FAQ

Authentication

Authentication Mechanisms

The Geoloqi API provides three authentication mechanisms depending on what kind of API request you are making.

  • Application Access Tokens are used when making requests for your application, such as setting up layers and triggers for an application, as well as managing users and subscribing to layers or groups.
  • User Access Tokens are used by apps when a user is logged in and making API requests.
  • API Key and Secret are used when applications need to create or delete users.

Application Access Tokens

To make requests on behalf of an application, you need an Application Access Token.

You can find an Application Access Token for your apps on your application list.

You can also programmatically create an Application Access Token by exchanging the API key and secret for an access token. Make a POST request like the following:

https://api.geoloqi.com/1/oauth/token
Post Body:
grant_type=client_credentials&client_id=YOUR_API_KEY
  &client_secret=YOUR_API_SECRET

You will get back an Application Access Token in the response.

You can use this access token for all regular API methods, such as creating layers, and you can use it to subscribe users you've created to those layers.

User Access Tokens

User access tokens are primarily used by mobile apps after a user has been created. The first time you create a user account, an access token is returned. If you wish to use the Geoloqi API to provide a "login" functionality for your app, you can use the API to get a new access token given a username (or email address) and password.

Username and Password

To get a User Access Token from a username and password, you can use one of the SDK methods ([LQSession requestSessionWithUsername:password:] on iPhone), or you can make an API request directly. The API request would look like this:

https://api.geoloqi.com/1/oauth/token
Post Body:
grant_type=password&client_id=YOUR_API_KEY&username=USERNAME&password=PASSWORD

API Key and Secret

The only time you need to use the API key and secret directly is when creating and deleting users, and using the authentication methods. In other words, only the user/* and oauth/token methods require API key and secret authentication.

You can get an API key and secret for your applications by visiting the application list page.

Creating User Accounts

There are three primary ways to create user accounts. Which you use is up to you and will depend on the kind of application you are making.

  • Anonymous Users have no login information, and require no identifier to be created. This method is typically used if you are making an application where you do not ask your users to log in, and you want the app to "just work" when they first download it.
  • Named Users have an email address or username as well as a password. Using this method, the Geoloqi API can be the account database for your application.
  • Unique Key: You can use a unique key to associate users in the Geoloqi API with your own user database.

Anonymous Users

The mobile SDKs provide methods you can use to quickly create anonymous users. The methods also handle storing the tokens returned to make the experience seamless when the user opens the app a second time.

When using any of these methods, the SDKs handle creating the account and registering a device with that account.

If you need to create an anonymous user account outside the SDKs, you can do so with the following POST request:

https://api.geoloqi.com/1/user/create_anon
Post Body:
client_id=YOUR_API_KEY

You can optionally store other properties in the user record if you need to store preferences or other things. This is done using the "extra" parameter as shown in the following request. Also see De-Duplication and Extra Parameters for more information.

https://api.geoloqi.com/1/user/create_anon
Post Body:
client_id=YOUR_API_KEY&extra[key]=value

You can also read the full API documentation for the user/create_anon method.

Named Users

If you would like the Geoloqi API to handle user logins for your application, you can use this method to create accounts in your app. Using this method is similar to creating anonymous users, except you provide an email address or username, and a password when creating the account. The SDKs have helper methods for this, or you can use the API directly.

You can also create a user using the user/create API method directly.

https://api.geoloqi.com/1/user/create
Post Body:
client_id=YOUR_API_KEY&username=USERNAME&password=PASSWORD

You can optionally store other properties in the user record if you need to store preferences or other things. This is done using the "extra" parameter. See De-Duplication and Extra Parameters for more information.

Unique Key

The easiest way to link an existing user database with the Geoloqi API is to use the unique key on user accounts. You can specify a "key" when using the user/create_anon method, and repeated calls with the same key will not create new accounts.

If a user already exists with the given key, that user's access token will be returned in the same way it was when the user was first created.

You can use this to easily tie your existing user database to Geoloqi accounts by using the primary key of your users as the "key" in the Geoloqi API. If you are building an SMS-based app, you could use the phone number as the key.

Here is an example request and response:

https://api.geoloqi.com/1/user/create_anon
Post Body:
client_id=YOUR_API_KEY&client_secret=YOUR_API_SECRET&key=1234567890

Response:

{
  "display_name": "Anonymous",
  "username": "_VcHVV1jAMgAqspHFz",
  "user_id": "PAE",
  "is_anonymous": 1,
  "key": "1234567890",
  "access_token": "56e-6d0916f445a2711d7e0eb61d1d5b47059c45be62",
  "extra": {
  }
}

Note that because this method can return an access token for an existing account, you must provide the API secret in addition to the API key. This means you can not use this from within an app or from the Javascript API, as it is not safe to include the API secret in distributed apps.

If you didn't provide the API secret, you will get the following error:

{
  "error_code": 409,
  "error": "duplicate_key",
  "error_description": "A user already exists with this key."
}

Using a User Access Token

Once you have obtained a User Access Token, you will need to include it in every request made on behalf of that user. The SDKs and client libraries will handle this automatically, and the SDKs will handle storing and retrieving the access token when the application re-launches.

If you are accessing the API directly, then you will need to include the access token in every request by adding an "Authorization" header as follows:

$ curl https://api.geoloqi.com/1/account/profile \
  -H "Authorization: OAuth 56f-e09938afd4c2a37908b1f69e7f75c449b16d689a"

It is also possible to pass the access token in the query string, but this is not a recommended solution. You should only do this if absolutely necessary, such as when using the API from Javascript and can't add HTTP headers.

https://api.geoloqi.com/1/account/profile?access_token=56f-e09938afd4c2a37908b1f69e7f75c449b16d689a

Using an Application Access Token

Once you have obtained an Application Access Token, you will need to include it in every request made to the API. The client libraries will handle this automatically. If you are accessing the API directly, you will need to include the access token in the "Authorization" header of every request:

$ curl https://api.geoloqi.com/1/layer/info/XXX \
  -H "Authorization: OAuth 56f-e09938afd4c2a37908b1f69e7f75c449b16d689a"

Some examples of things you can do with an Application Access Token:

  • Create a public layer that your users will be subscribed to when they download your app
  • Subscribe or un-subscribe users to your layers
  • Retrieve a list of users at each place on a layer by using layer/users/:id

When you are manipulating user accounts as the application, you will always need to include the user_id in the request. For example, to subscribe user NNN to layer YYY, make a request like the following:

$ curl https://api.geoloqi.com/1/layer/subscribe/YYY \
  -H "Authorization: OAuth 56f-e09938afd4c2a37908b1f69e7f75c449b16d689a" \
  -d user_id=NNN

How the Geoloqi SDKs Manage Authentication

The Geoloqi iOS and Android SDKs will handle most of the authentication process for you. Both provide methods to create users and log users in, and they store the access token on the device.

When making API requests from the SDKs, the access token will automatically be included in the request, so you don't have to worry about it.

Note that you should never include the API Secret in your app's source code, as it is possible for someone to reverse engineer and discover the secret. The API secret can be used to get access to your application account and the user data associated with all users, so this must be kept confidential.