Was this helpful?

With the exception of the 'sandbox' application that is created with your App Services account, all applications are secured by default. This means that to access your data store, a valid access token must be sent with all API requests to authenticate that the requester is authorized to make API calls to the resources they are attempting the access.

This article describes how to use access tokens to access the App Services API, and how to manage access tokens, including revoking and changing token time to live.

For information on generating access tokens/authenticating users and clients, see Authenticating users and application clients.

Authenticating with access tokens

When you obtain an access token, you must provide it with every subsequent API call that you make. There are two ways to provide your access token.

  • You can add the token to the API query string:
  • You can include the token in an HTTP authorization header:
    Authorization: Bearer {access_token}
Note: The App services documentation assumes you are providing a valid access token with every API call whether or not it is shown explicitly in the examples. Unless the documentation specifically says that you can access an API endpoint without an access token, you should assume that you must provide it. One application that does not require an access token is the sandbox application. The Guest role has been given full permissions (/** for GET, POST, PUT, and DELETE) for this application. This eliminates the need for a token when making application level calls to the sandbox app. For further information on specifying permissions, see Managing access by defining permission rules.

Changing token time-to-live

An access token has a “time-to-live”, which is the maximum time that the access token will be valid for use within the application, specified in milliseconds. By default, all tokens have a system-defined time-to-live of 24 hours.

Changing the default time-to-live

You can change the default time-to-live for all application tokens by updating the Application entity’s accesstokenttl property. 

For example, the following updates an application entity to have a default time-to-live value of 1800000 miliseconds (30 minutes) for all tokens:

curl -X PUT -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app" -d '{"accesstokenttl":"1800000"}'

Changing token time-to-live

When you request an access token, you can override its time-to-live by including a ttl parameter in the request.

The ttl value must be equal to or less than the value of the accesstokenttl property. If you specify a ttl value greater than the value of accesstokenttl, an error message is returned that indicates the maximum time to live value that can be specified.

Note: If you set ttl=0, the token will never expire. This can pose a security risk and should be used with caution.

For example, the following sets a time to live value of 1800000 miliseconds (30 minutes) for an admin user:

curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/management/token?ttl=1800000" -d '{"grant_type":"client_credentials","client_id":"YXB7NAD7EM0MEeJ989xIxPRxEkQ","client_secret":"YXB7NAUtV9krhhMr8YCw0QbOZH2pxEf"}'

The following sets the same time to live value for an application user.

curl -X POST -i -H "Content-Type: application/json" "https://api.usergrid.com/my-org/my-app/token?ttl=1800000" -d '{"grant_type":"password","username":"testadmin","password":"testadminpw"}'

Revoking access tokens

Under certain circumstances, you may need to explicitly revoke a user's access token, such as when a user logs out. To revoke a specific access token, send the following PUT request:

curl -X PUT https://api.usergrid.com/<org_name>/<app_name>/users/<user_uuid_or_username>/revoketokens?token="<token>"

If the token is successfully revoked, you will receive the following response from the API:

  "action" : "revoked user token",
  "timestamp" : 1382050891455,
  "duration" : 24

Authenticating with client ID and client secret

Another option for authenticating your API requests is using either your organization client ID and client secret, or your application client ID and client secret, which will authenticate your request as an organization or application, respectively. Organization credentials can be found in the 'Org Overview' section of the admin portal, and application credentials can be found in the 'Getting Started' section of the admin portal.

Warning: For server-side use only

You should never authenticate this way from a client-side app such as a mobile app. A hacker could analyze your app and extract the credentials for malicious use even if those credentials are compiled and in binary format. See Safe mobile access for additional considerations in keeping access to your app and its data secure.

This can be a convenient way to authenticate API requests, since there is no need to generate and manage an access token, but please note that you should be very cautious when implementing this type of authentication. Organization-level authentication grants full permission to perform any supported call against your organization and every application in it, and application-level authentication grants full permission to perform any supported call against all of the resources in an application. Should your client id and client secret be compromised, a malicious user would gain broad access to your organization or application.

To authenticate using client id and secret, append the following parameters to your request URL:


Safe mobile access

For mobile access, it is recommended that you connect as an application user with configured access control policies. Mobile applications are inherently untrusted because they can be easily examined and even decompiled.

Any credentials stored in a mobile app should be considered secure only to the Application User level. This means that if you don’t want the user to be able to access or delete data in your App Services application, you need to make sure that you don’t enable that capability through roles or permissions. Because most web applications talk to the database using some elevated level of permissions, such as root, it’s generally a good idea for mobile applications to connect with a more restricted set of permissions. For more information on restricting access through permission rules, see Managing access by defining permission rules.

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.