Generate API tokens

The AmigoCloud API is designed so that it's really easy to be accessed by applications, devices, even from the command line.

If you want an application to use the AmigoCloud API, the first problem you will encounter is how to authenticate your requests. The solution for this problem is to generate an API token. You should only provide tokens to applications you know and trust.

To manage your API tokens, follow these steps:

1. Click on your email (upper left corner) and select "API Tokens":

2. Here you'll see a list of all your existing tokens. Something like this:

4. Now you're just a couple of clicks away from generating a new token. Write a descriptive name, choose the right permission level, select the type of token (and project in case it's a Project token), and whether you want the token to expire or not. For security purposes, you won't be able to edit the token once it has been generated, so double check before creating it.

5. That's it, you just generated your first API token! Click on it, copy it, and start using it.

What's the permission level?

The permission level limits the permissions that the user/application/device using your token will have:

• READ: Access to all actions that don't alter data, e.g. list projects and datasets, query data, request exports, etc.
• CREATE: Access to all READ actions, plus permission to create data, e.g. create records, upload photos, etc.
• EDIT: Access to all CREATE actions, plus permission to edit  and delete data.
• ADMIN: Full access (uploading datasources, creating and deleting datasets, editing schema, adding collaborators, etc.).

Some actions are not available at all when using tokens, like deleting projects, because of its destructive nature.

What's the difference between User tokens and Project tokens?

User tokens give full access to all the resources that you as a user have. This means access to all the projects you have access to (yours and shared with you), as well as access to your user data. This token most likely should be only used by you.

Project tokens are bounded to a single project, giving access only to its resources (datasets, base layers, tiles, etc.). This is the token you should be using most of the time. 

Should I make my tokens expirable?

If you set a expiration for your token, you won't be able to use it once it has expired. Setting an expiration time is recommended as a security measure. If you don't want to make your tokens expirable, you can delete them if you aren't not going to use it any longer, or if you think someone unauthorized might have had access to it.

What to do next?

Take a look at the other articles in this section, like Use the Python client.