SpatiaFi Auth API (0.1.0.dev48+g9321756)

Download OpenAPI specification:Download

SpatiaFi Authentication API

This API is used to authenticate users and services to SpatiaFi. Ultimately, the goal of this API is to provide Access Tokens that can be used to authenticate to the SpatiaFi APIs.

The following API reference docs are technical in nature and are intended for developing integrations with SpatiaFi. For information on how to use SpatiaFi, please see the SpatiaFi Documentation.

Access Token

Authentication to SpatiaFi is done via OAuth 2.0. OAuth 2.0 is a standard for authentication used by Google, Facebook, and many other services. One of the security features of OAuth 2.0 is that access tokens are short lived and can be revoked at any time. This means that if your access token is compromised, you can simply request a new one and the old one will no longer work. This may be different from other services you've used, where you might have a single API key that never expires.

Using an OAuth 2.0 API requires the following steps:

  1. Get a (short lived) access token from the authentication API
  2. Use the access token to make requests to the main API
  3. (Optional) Refresh the access token when it expires

The following routes allow you to get a new access token that can be used to make requests to the API. For information on automatically refreshing the access token, or creating App Credentials (used to authenticate with the API programmatically without entering your password), see the App Credentials section below.

Get access token (for humans)

Use HTTP Basic Auth to retrieve a temporary access token. Recommended for testing only.

The access token returned is only valid for 15 minutes, but can be used to generate App Credentials that are longer lasting.

SecurityHTTPBasic
Responses
200

Successful Response

400

Bad Request

get/api/v1/auth/jwt/token/basic
Request samples
Response samples
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI",
  • "token_type": "bearer",
  • "expires_at": 1648925200
}

Get access token (for robots)

🚷 Not for humans The information included here is for reference only, as details generally be automatically handled with an OAuth2 client library that supports these authentication methods (e.g. authlib for Python). The following information is very technical and not required for most users.

This token endpoint supports OAuth 2.0 password and client_credentials grant types.

password grant type:

In order to get an access token with password grant type, do a POST request to /api/v1/auth/jwt/token endpoint with the POST parameters grant_type=password, username=<your_email> and password=<your_password>. On successful authentication, the response will include an access token that is valid for ~15 minutes, along with some expiration information. This grant type is useful for testing, but for production systems it is recommended to use App Credentials (see below).

(client_id and client_secret fields are not required for password grant)

client_credentials grant type:

In order to get an access token with client_credentials grant type, you use your previously generated client_id and client_secret through one of the supported methods below:

  • client_secret_basic: Provide client_id and client_secret as username and password in HTTP Basic authorization header.
  • client_secret_post: Provide client_id and client_secret as POST parameters
  • client_secret_jwt: Mint a JWT as described in the spec and sign it with client_secret. Set client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer POST parameter, and include the JWT in client_assertion POST parameter.

While client_secret_jwt is the most complex, it is also the most secure and is recommended for production use.

scope is currently ignored, and should be left blank.

SecurityHTTPBasic or APIKeyCookie
Request
Request Body schema: application/x-www-form-urlencoded
grant_type
string (GrantType)
Default: "password"

Must be one of the supported grant types

Enum: "password" "client_credentials" "refresh_token_cookie"
username
string (Username)
password
string (Password)
scope
string (Scope)
client_id
string (Client Id)
client_secret
string (Client Secret)
client_assertion_type
string (Client Assertion Type)
Value: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
client_assertion
string (Client Assertion)
Responses
200

Successful Response

400

Bad Request

422

Validation Error

post/api/v1/auth/jwt/token
Request samples
application/x-www-form-urlencoded
grant_type=password&username=string&password=string&scope=string&client_id=string&client_secret=string&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=string
Response samples
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI",
  • "token_type": "bearer",
  • "expires_at": 1648925200
}

App Credentials

App Credentials (technically an "OAuth 2.0 Client") are used to authenticate with the API programmatically.

By creating an app credential, you will be given a client_id and client_secret. The client_secret is essentially the password for the app credential. It should be treated like a password and should never be shared with anyone. The client_secret is only shown during app credential creation and can't be accessed later, so save it somewhere safe.

It is also good practice to use a different app credential for each app you create, and to delete credentials that are no longer in use.

In order to create new app credentials, you must have a valid access token - usually obtained by using the HTTP Basic Auth endpoint.

With a valid access token, you can make an empty POST request to /api/v1/clients, with the Authorization header set to Bearer {access_token}, and new app credentials will be created for you. The response will contain the client_id and client_secret.

If you need to revoke an app credential, you can make a DELETE request to /api/v1/clients/{client_id}.

Note: While there is no limit to the number of app credentials you can create, this may change in the future. Please store and reuse app credentials instead of creating new ones for each request.

Create App Credentials

Create new App Credentials (client_id and client_secret) pair for machine authentication.

owner_id feild should be left blank. It will be automatically set to the current user's id.

client_secret will only be returned once. If you lose it, please delete the client and create a new one.

SecurityOAuth2ClientBearer or OAuth2PasswordBearer
Request
Request Body schema: application/json
owner_id
string <uuid4> (Owner Id)
Responses
201

Successful Response

422

Validation Error

post/api/v1/clients
Request samples
application/json
{ }
Response samples
application/json
{
  • "user_id": "string",
  • "client_id": "string",
  • "client_secret": "string"
}

List App Credentials

List all App Credentials owned by the current user.

SecurityOAuth2ClientBearer or OAuth2PasswordBearer
Responses
200

Successful Response

422

Validation Error

get/api/v1/clients
Request samples
Response samples
application/json
[
  • {
    }
]

Delete App Credentials

Delete App Credentials and associated client_id and client_secret pair.

SecurityOAuth2ClientBearer or OAuth2PasswordBearer
Request
path Parameters
client_id
required
string <uuid4> (Client Id)
Responses
204

Successful Response

422

Validation Error

delete/api/v1/clients/{client_id}
Request samples
Response samples
application/json
{
  • "detail": [
    ]
}
Copyright © SpatiaFi/Climate Engine 2023. All right reserved.