MariaDB SkySQL API Keys
This page is part of MariaDB's Documentation.
The parent of this page is: Security
Topics on this page:
Overview
Users with MariaDB ID accounts are able to request SkySQL API Keys that are used to securely access automated interfaces in MariaDB SkySQL:
The SkySQL DBaaS API requires a SkySQL API Key to create, delete, and modify database services
The SkySQL Observability service requires a SkySQL API key to monitor on-premises database services
SkySQL API Key Scopes
Each SkySQL API Key is associated with one or more key scopes that determines what the API key can be used for.
Multiple scopes are currently available:
Scope | Description |
---|---|
Observability API: Read | Allows |
Observability API: Write | Allows write requests to the SkySQL Observability service |
SkySQL API: Databases: Read | Allows |
SkySQL API: Databases: Write | Allows write requests to the SkySQL DBaaS API |
List SkySQL API Keys
To list your SkySQL API Keys, go to the API Keys page.
Generate a SkySQL API Key
To generate a SkySQL API Key:
Go to the Generate API Key page.
Fill out the API key details:
In the "Description" field, describe the purpose of the API key.
In the "Scopes" field, select one or more API key scopes.
Click the "Generate API Key" button.
After the page refreshes, click the "Copy to clipboard" button to copy the API key.
Paste the API key somewhere safe and do not lose it.
Verify a SkySQL API Key
To verify a SkySQL API Key, use the keyinfo
endpoint:
A
GET
request must be sent to the MariaDB ID URL: https://id.mariadb.com/api/v1/keyinfo/The
Authorization
header must be in the formatAuthorization: Token SKYSQL_API_KEY
, whereSKYSQL_API_KEY
refers to the API key.The
Content-length
header must set the content length to0
.
For example, to verify a SkySQL API Key using cURL with the output piped to jq
for readability:
$ curl --location \
--header 'Authorization: Token SKYSQL_API_KEY' \
--header 'Content-length: 0' \
https://id.mariadb.com/api/v1/keyinfo/ \
| jq .
{
"jti": "JTI",
"email": "[email protected]",
"full_name": "Example User",
"key_prefix": "YpnHA",
"description": "My new API key",
"exp": null,
"iat": "2021-11-10T17:45:00.823041Z",
"scopes": [
"skysql::database::write"
],
"iss": "id.mariadb.com",
"entitlements": [
"enterprise",
"xpand",
"monitoring",
"skysql"
]
}
The full set of fields in the output are:
Field | Description |
---|---|
| A list of entitlements this user has access to |
| Time when this API key will expire |
| Time when this API key was issued |
| The server that issued this API key |
| The email address of the user who generated this API key |
| A unique GUID for this API key |
| The key ID used to sign this API key |
| The API key scopes of the API key |
Request a Bearer Token
Most automated interfaces in SkySQL do not directly use the SkySQL API Key directly. Instead, the SkySQL API Key is exchanged for a short-lived bearer token that expires after 1 hour.
To request a short-lived bearer token using a SkySQL API Key, use the token
endpoint:
A
POST
request must be sent to the MariaDB ID URL: https://id.mariadb.com/api/v1/token/The
Authorization
header must be in the formatAuthorization: Token SKYSQL_API_KEY
, whereSKYSQL_API_KEY
refers to the API key.The
Content-length
header must set the content length to0
.
For example, to request a bearer token using cURL with the output piped to jq
for readability:
$ curl --location --request POST \
--header 'Authorization: Token SKYSQL_API_KEY' \
--header 'Content-length: 0' \
https://id.mariadb.com/api/v1/token/ \
| jq .
{
"jti": "JTI",
"email": "[email protected]",
"full_name": "Example User",
"exp": "2021-11-03T23:04:28.834462Z",
"iat": "2021-11-03T22:04:28.835032Z",
"scopes": [
"skysql::database::write"
],
"iss": "id.mariadb.com",
"parent": "PARENT_ID",
"token": "SKYSQL_BEARER_TOKEN",
"entitlements": [
"enterprise",
"xpand",
"monitoring",
"skysql"
],
"tenant_id": "TENANT_ID"
}
In the output, the bearer token is returned as the value of the "token"
key. This value is used by most automated interfaces in MariaDB SkySQL.
The full set of fields in the output are:
Field | Description |
---|---|
| A list of entitlements this user has access to |
| Time when this bearer token will expire |
| Time when this bearer token was issued |
| The server that issued this bearer token |
| The email address of the user who generated this bearer token |
| A unique GUID for this bearer token |
| The key ID used to sign this bearer token |
| The unique ID of the SkySQL API Key that issued this bearer token |
| The API key scopes of the SkySQL API Key that issued this bearer token |
| The SkySQL Billing ID of the user who generated this bearer token |
Expiration
SkySQL API Keys expire.
The expiration interval is chosen when the API key is generated. SkySQL API Keys can expire at the following intervals:
2 years
1 year
9 months
6 months
3 months
Revocation
SkySQL API Keys can be revoked.
To revoke a SkySQL API Key:
Go to the API Keys page
Click the "Revoke" button for the API key