Initial commit
This commit is contained in:
zhongjin
@@ -0,0 +1,20 @@
|
||||
## CARTO Authorization
|
||||
|
||||
All requests to CARTO's APIs (Maps, Sql, etc.) require you to authenticate with an API Key.
|
||||
API Keys identify your project and provide a powerful and flexible primitive for managing access to CARTO's resources like APIs and Datasets.
|
||||
|
||||
These API Keys can be provisioned, revoked and regenerated through the [Auth API]({{site.authapi_docs}}/reference/) or the dashboard. You are able to manage authorization through the UI, by [logging on to your CARTO account](https://carto.com) and managing everything in there. Here you have an example of the authorization dashboard in a real CARTO account.
|
||||
|
||||
|
||||
|
||||
And here you can see the process of creating a new API key, managing its name and resources in terms of APIs and Datasets, including its permissions.
|
||||
|
||||
It requires to add a name and grant permission for at least one of these:
|
||||
* SQL API: you will have to include CREATE datasets or specific permissions on any table.
|
||||
* MAPS API: you will have to specify SELECT permissions on any table.
|
||||
* CREATE datasets: allows you to create tables in the user schema by using the SQL API, and also modify or delete the tables previously created with it. It won't allow to modify or delete a table created with a different API key, in that case you'll receive an `Access denied` error.
|
||||
* LISTING datasets: allows to read the metadata from the existing tables, views and materialized views in the user schema by using the endpoint: `api/v4/datasets`
|
||||
|
||||
|
||||
|
||||
**Warning:** Changes to the key permissions are not possible once key is generated.
|
||||
@@ -0,0 +1,78 @@
|
||||
## How to send API Keys
|
||||
|
||||
A CARTO API Key is physically a token/code of 12+ random alphanumeric characters.
|
||||
|
||||
You can pass in the API Key to our APIs either by using the HTTP Basic authentication header or by sending an `api_key` parameter via the query string or request body.
|
||||
|
||||
**Tip:** If you use our client library CARTO.js, you only need to follow the authorization section and we will handle API Keys automatically for you.
|
||||
|
||||
The examples shown to illustrate the different methods of how to send API Keys use the following parameters:
|
||||
|
||||
```
|
||||
- user: username
|
||||
- API Key: 1234567890123456789012345678901234567890
|
||||
- API endpoint: https://username.carto.com/endpoint/
|
||||
```
|
||||
|
||||
|
||||
### HTTP Basic Authentication
|
||||
|
||||
Basic Access Authentication is the simplest technique of handling access control and authorization in a standardized way. It consists essentially of an `HTTP Authorization Basic` header followed by the user credentials (username and password) encoded using base64.
|
||||
|
||||
If that looks complicated to you, don’t worry. Most client software provide simple mechanisms to use HTTP Basic Authentication, like [curl](https://ec.haxx.se/http-auth.html), [Request](https://github.com/request/request#http-authentication) (JavaScript) and [Requests](http://docs.python-requests.org/en/master/user/authentication/#basic-authentication) (Python).
|
||||
|
||||
For requests to CARTO’s APIs, take the API Key as the password, and the username as the user who issued that API Key.
|
||||
|
||||
#### Examples:
|
||||
|
||||
##### Curl
|
||||
|
||||
```bash
|
||||
curl -X GET \
|
||||
'https://username.carto.com/endpoint/' \
|
||||
-H 'authorization: Basic dXNlcm5hbWU6MTIzNDU2Nzg5MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNDU2Nzg5MA=='
|
||||
```
|
||||
|
||||
##### Request (JavaScript)
|
||||
|
||||
```javascript
|
||||
request.get('https://username.carto.com/endpoint/', {
|
||||
'auth': {
|
||||
'user': 'username',
|
||||
'pass': 1234567890123456789012345678901234567890
|
||||
}
|
||||
});
|
||||
```
|
||||
|
||||
##### Requests (Python)
|
||||
```python
|
||||
r = requests.get('https://username.carto.com/endpoint/', auth=(username, 1234567890123456789012345678901234567890))
|
||||
```
|
||||
|
||||
### Query string/Request body parameter
|
||||
|
||||
Alternatively, you can use an URL query string parameter or a field in the request body. In both cases, the name of the parameter is `api_key`.
|
||||
|
||||
#### Examples:
|
||||
|
||||
```bash
|
||||
curl -X GET 'https://username.carto.com/endpoint/?api_key=1234567890123456789012345678901234567890'
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -X POST \
|
||||
'https://username.carto.com/endpoint/' \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{
|
||||
"api_key": "1234567890123456789012345678901234567890"
|
||||
}'
|
||||
```
|
||||
|
||||
|
||||
If, for some mysterious reason, you submit the API Key with more than one of the available methods, the order of precedence is as follows:
|
||||
|
||||
1. HTTP Basic Authentication header
|
||||
2. URL query string parameter
|
||||
3. Request body field
|
||||
|
||||
Likewise, for security reasons and future-proofing, we recommend that you use that same order when choosing a method for sending the API Key. In other words, favour the use of HTTP Basic Authentication over the URL query string, and try to avoid the body field. We support this method just for backwards compatibility.
|
||||
@@ -0,0 +1,78 @@
|
||||
## Types of API Keys
|
||||
|
||||
In CARTO, you can find 3 types of API Keys:
|
||||
|
||||
- Regular
|
||||
- Default public
|
||||
- Master
|
||||
|
||||
|
||||
#### Regular
|
||||
|
||||
Regular API Keys are the most common type of API Keys. They provide access to APIs and database tables (AKA datasets) in a granular and flexible manner.
|
||||
|
||||
For example one API key can provide access to:
|
||||
|
||||
- The SQL API
|
||||
- The `world_population` dataset with select permission
|
||||
- The `liked_cities` dataset with select/insert permissions
|
||||
- Creating new datasets in the user account
|
||||
- Listing existing datasets in the user account
|
||||
|
||||
With this API Key you can:
|
||||
|
||||
- Access the SQL API, but not the Maps API.
|
||||
- Run a `SELECT SQL` query to the `world_population` dataset, but not an `UPDATE`, `DELETE` or `INSERT`.
|
||||
- Run an `INSERT` to the `liked_cities` dataset, but not to `national_incomes`.
|
||||
- Run `CREATE TABLE AS...` SQL queries to create new tables in the user account. As the owner of the tables created you'll also be able to `DROP` and `ALTER` the created tables.
|
||||
- Read metadata (like name or privacy) from `national_incomes`, but not its content.
|
||||
|
||||
It's possible to create as many regular API Keys as you want. Moreover, to enforce security, we encourage you to create as many regular API Keys as apps/maps you produce. Since regular API Keys can be independently revoked, you have complete control of the lifecycle of your API credentials.
|
||||
|
||||
An important property to keep in mind about regular API Keys is that they are *not editable*. You can not add/delete datasets nor APIs. It’s designed this way on purpose for security reasons.
|
||||
|
||||
Another important property of Regular API keys is that they inherit all the datasets permissions from the Default Public API Key.
|
||||
|
||||
You can see below an example of a real API key as it is displayed in a CARTO account.
|
||||
|
||||
|
||||
|
||||
#### Default Public
|
||||
|
||||
Default public are a kind of regular API Keys. They too provide access to APIs and datasets, but for the latter in a read-only way.
|
||||
|
||||
Every user has one and only one Default Public API Key. That means that on user creation a Default API Key is issued for that user, and that these type of keys are not revocable/deletable.
|
||||
|
||||
For example one Default Public API Key can provide access to
|
||||
|
||||
- the SQL API
|
||||
- the Maps API
|
||||
- the `world_population` dataset with read permission
|
||||
- the `liked_cities` dataset with read permission
|
||||
|
||||
As you can see, API and read-only selected datasets access are possible.
|
||||
|
||||
At the beginning of this authentication section we stated that all API requests require an API Key. Well, we lied a little bit. If none is provided, the Default Public API Key is used as a fall back.
|
||||
|
||||
**Warning:** This is done for backwards compatibility reasons. Don’t expect this behaviour to be maintained in the long term, it can be deprecated.
|
||||
|
||||
Get used to always send an API Key, even if it’s the Default Public.
|
||||
|
||||
A cosmetic difference compared to the other API Key types is the code/token that identifies these API Keys, it’s just: _default_public_. It’s a simple human-readable constant string, no randoms involved.
|
||||
|
||||
|
||||
#### Master
|
||||
|
||||
Master keys are a very special kind of API Keys. As it happens with the Default Public type, every user has one and only one Master non revocable API Key.
|
||||
|
||||
The special thing about Master API Keys is that they grant access to EVERYTHING: APIs and datasets (select/insert/create/delete). Additionally, a Master API Key is required to access most of the Auth API endpoints.
|
||||
|
||||
Your Master API key carries many privileges, so be sure to keep it secret. Do not share it in publicly accessible areas such as GitHub or client-side code.
|
||||
|
||||
Below you have an example of a master API key.
|
||||
|
||||
|
||||
|
||||
**Tip:** If you think is has been compromised, regenerate it immediately.
|
||||
|
||||
Actually, you should use Master API Keys sparingly. Try to limit its direct use only to interact programmatically with the [Auth API]({{site.authapi_docs}}/reference/). Issue and use regular API Keys for the rest of use cases.
|
||||
@@ -0,0 +1,9 @@
|
||||
## General Considerations
|
||||
|
||||
- Regenerate a regular/master API Key if you suspect it has being compromised. A regenerated API Key grants the same permissions as before, but has a new code/token. Maps/apps using a regenerated API Key must be updated to adapt to that change, otherwise they will stop working.
|
||||
- Send always an API Key in your API requests
|
||||
- Issue a new regular API Key per map/app. Try to avoid sharing keys between maps/apps
|
||||
- Grant the least amount of necessary permissions per API Key
|
||||
- Use the Master API Key sparingly
|
||||
- Keep your Master API Key secret!
|
||||
- Do not overuse the Default Public API Key. It’s meant for obviously public Datasets.
|
||||
@@ -0,0 +1,45 @@
|
||||
## Authorization for CARTO views
|
||||
|
||||
With the [CARTO Auth API](https://carto.com/developers/auth-api/), it is possible to create API Keys not only for tables in CARTO (aka datasets), but also for Views in CARTO.
|
||||
|
||||
CARTO use PostgreSQL as the database to store your datasets, so you can create a View in CARTO in the same way that it is created in PostgreSQL. We would recommend checking [this section](https://www.postgresql.org/docs/9.5/static/tutorial-views.html) of the PostgreSQL documentation if you want to learn more about how Views are created in PostgreSQL.
|
||||
|
||||
What is the advantage of using a View with the CARTO Auth API? Well, in order to answer that question, let's assume that you have a dataset in CARTO and you want to restrict partial information of your dataset when publishing a map or using the SQL API. For example, you might have a dataset named `clients` with [private privacy](https://carto.com/learn/guides/publish-share/privacy-settings-for-protecting-maps-and-data/) and you want to build a map with clients of New York area only, so you can create a View as it is done in the next block of code:
|
||||
|
||||
```sql
|
||||
CREATE VIEW clients_nyc AS (
|
||||
SELECT * FROM clients WHERE area = 'NY'
|
||||
);
|
||||
```
|
||||
|
||||
Now, you would need to use the Auth API in order to create the API Key for the View with a payload that sets the permissions of the new API Key that will be created. In this example, we are giving read-only or select permission to our View so it can only be available when using the API key with the [CARTO Maps API](https://carto.com/developers/maps-api/) or [CARTO.js](https://carto.com/developers/carto-js/).
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "Clients-NYC",
|
||||
"grants": [
|
||||
{
|
||||
"type": "apis",
|
||||
"apis": [
|
||||
"maps"
|
||||
]
|
||||
},
|
||||
{
|
||||
"type": "database",
|
||||
"tables": [
|
||||
{
|
||||
"schema": "public",
|
||||
"name": "clients_nyc",
|
||||
"permissions": [
|
||||
"select"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If you try to access to the data of this View using the [CARTO SQL API](https://carto.com/developers/sql-api/), you will receive a forbidden error, because this API Key do not have permissions to be accessed using the CARTO SQL API.
|
||||
|
||||
So, by creating API Keys for the Views in CARTO using the Auth API, we can display the information partial information that we want and at the same time, keeping our data private.
|
||||
Reference in New Issue
Block a user