Download OpenAPI specification:Download
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.
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:
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.
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.
Successful Response
Bad Request
{- "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI",
- "token_type": "bearer",
- "expires_at": 1648925200
}🚷 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.
authlibfor 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 parametersclient_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.
Successful Response
Bad Request
Validation Error
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
{- "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyX2lkIjoiOTIyMWZmYzktNjQwZi00MzcyLTg2ZDMtY2U2NDJjYmE1NjAzIiwiYXVkIjoiZmFzdGFwaS11c2VyczphdXRoIiwiZXhwIjoxNTcxNTA0MTkzfQ.M10bjOe45I5Ncu_uXvOmVV8QxnL-nZfcH96U90JaocI",
- "token_type": "bearer",
- "expires_at": 1648925200
}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 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_secretwill only be returned once. If you lose it, please delete the client and create a new one.
Successful Response
Validation Error
{ }{- "user_id": "string",
- "client_id": "string",
- "client_secret": "string"
}List all App Credentials owned by the current user.
Successful Response
Validation Error
[- {
- "user_id": "string",
- "client_id": "string"
}
]Delete App Credentials and associated client_id and client_secret pair.
Successful Response
Validation Error
{- "detail": [
- {
- "loc": [
- "string"
], - "msg": "string",
- "type": "string"
}
]
}