Spatio.Api.OAuth (spatio_sdk v0.0.2)

API calls for all endpoints tagged OAuth.

Summary

Functions

JSON Web Key Set for id_token verification (RFC 7517). The set of public keys RPs use to verify Spatio-issued id_tokens. Cached for 5 minutes at the edge. Always includes the currently-active signing key plus any retired keys that may still be in circulation (id_token TTL is 1 hour + slack).

get_o_auth_discovery(connection, opts \\ [])

OAuth 2.1 authorization server metadata (RFC 8414). Returns the canonical metadata for the Spatio OAuth 2.1 + OpenID Connect server. Third-party RPs use this to auto-discover endpoint URLs, supported scopes, and signing algorithms. Identical payload to /.well-known/openid-configuration — either path is acceptable; OIDC clients prefer the openid-configuration alias.

get_open_id_configuration(connection, opts \\ [])

OpenID Connect Discovery 1.0 metadata. Alias of /.well-known/oauth-authorization-server. Provided so OIDC client libraries (NextAuth, Auth.js, oidc-client-ts, passport-openidconnect) auto-detect Spatio as an OIDC provider via their wellKnown / discoveryUrl config field.

get_user_info(connection, opts \\ [])

OIDC UserInfo (OpenID Connect Core 1.0 §5.3). Returns user claims gated by the scopes on the presenting access token. sub is always returned; email, name, etc. require their respective scopes.

oauth_authorize(connection, client_id, redirect_uri, response_type, code_challenge, code_challenge_method, opts \\ [])

OAuth 2.1 authorization endpoint (RFC 6749 + 7636 PKCE). Browser-redirect endpoint. Validates the client + redirect_uri, packs the request into a signed JWT, and 302s the user's browser to the consent UI. The consent UI then POSTs to /oauth2/authorize/confirm with the user's decision. OIDC additions: scope=openid+profile+email, nonce, prompt (none|login|consent), max_age.

oauth_introspect(connection, token, opts \\ [])

RFC 7662 token introspection. Accepts both OAuth access tokens and PATs.

oauth_revoke(connection, token, opts \\ [])

RFC 7009 token revocation. Idempotent.

oauth_token(connection, grant_type, opts \\ [])

Exchange authorization code or refresh token for an access token (+ id_token if openid scope).

post_user_info(connection, opts \\ [])

Same as GET /oauth2/userinfo. Provided for clients that send the bearer in the body.

register_o_auth_client(connection, client_registration_request, opts \\ [])

Register a new OAuth 2.1 client (RFC 7591 dynamic client registration). Returns a fresh client_id (and, for confidential clients, client_secret) plus a one-time registration_access_token the client can use later to update its registration. Public clients (mobile, SPA) MUST use token_endpoint_auth_method: none and PKCE. Rate-limited to 10 registrations per hour per source IP.

Functions

get_jwks(connection, opts \\ [])

@spec get_jwks(
  Tesla.Env.client(),
  keyword()
) :: {:ok, Spatio.Model.Jwks.t()} | {:error, Tesla.Env.t()}

Parameters

connection (Spatio.Connection): Connection to server
opts (keyword): Optional parameters

Returns

{:ok, Spatio.Model.Jwks.t} on success
{:error, Tesla.Env.t} on failure

get_o_auth_discovery(connection, opts \\ [])

@spec get_o_auth_discovery(
  Tesla.Env.client(),
  keyword()
) :: {:ok, Spatio.Model.DiscoveryDocument.t()} | {:error, Tesla.Env.t()}

Parameters

connection (Spatio.Connection): Connection to server
opts (keyword): Optional parameters

Returns

{:ok, Spatio.Model.DiscoveryDocument.t} on success
{:error, Tesla.Env.t} on failure

get_open_id_configuration(connection, opts \\ [])

@spec get_open_id_configuration(
  Tesla.Env.client(),
  keyword()
) :: {:ok, Spatio.Model.DiscoveryDocument.t()} | {:error, Tesla.Env.t()}

Parameters

connection (Spatio.Connection): Connection to server
opts (keyword): Optional parameters

Returns

{:ok, Spatio.Model.DiscoveryDocument.t} on success
{:error, Tesla.Env.t} on failure

get_user_info(connection, opts \\ [])

@spec get_user_info(
  Tesla.Env.client(),
  keyword()
) ::
  {:ok, nil}
  | {:ok, Spatio.Model.UserInfoResponse.t()}
  | {:error, Tesla.Env.t()}

OIDC UserInfo (OpenID Connect Core 1.0 §5.3). Returns user claims gated by the scopes on the presenting access token. sub is always returned; email, name, etc. require their respective scopes.

Parameters

connection (Spatio.Connection): Connection to server
opts (keyword): Optional parameters

Returns

{:ok, Spatio.Model.UserInfoResponse.t} on success
{:error, Tesla.Env.t} on failure

oauth_authorize(connection, client_id, redirect_uri, response_type, code_challenge, code_challenge_method, opts \\ [])

@spec oauth_authorize(
  Tesla.Env.client(),
  String.t(),
  Uri,
  String.t(),
  String.t(),
  String.t(),
  keyword()
) :: {:ok, nil} | {:error, Tesla.Env.t()}

Parameters

connection (Spatio.Connection): Connection to server
client_id (String.t):
redirect_uri (Uri):
response_type (String.t):
code_challenge (String.t):
code_challenge_method (String.t):
opts (keyword): Optional parameters
- :scope (String.t):
- :state (String.t):
- :nonce (String.t):
- :prompt (String.t):
- :max_age (integer()):

Returns

{:ok, nil} on success
{:error, Tesla.Env.t} on failure

oauth_introspect(connection, token, opts \\ [])

@spec oauth_introspect(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, Spatio.Model.IntrospectionResponse.t()} | {:error, Tesla.Env.t()}

RFC 7662 token introspection. Accepts both OAuth access tokens and PATs.

Parameters

connection (Spatio.Connection): Connection to server
token (String.t):
opts (keyword): Optional parameters

Returns

{:ok, Spatio.Model.IntrospectionResponse.t} on success
{:error, Tesla.Env.t} on failure

oauth_revoke(connection, token, opts \\ [])

@spec oauth_revoke(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, nil} | {:error, Tesla.Env.t()}

RFC 7009 token revocation. Idempotent.

Parameters

connection (Spatio.Connection): Connection to server
token (String.t):
opts (keyword): Optional parameters

Returns

{:ok, nil} on success
{:error, Tesla.Env.t} on failure

oauth_token(connection, grant_type, opts \\ [])

@spec oauth_token(Tesla.Env.client(), String.t(), keyword()) ::
  {:ok, Spatio.Model.OAuthError.t()}
  | {:ok, Spatio.Model.TokenResponse.t()}
  | {:error, Tesla.Env.t()}

Exchange authorization code or refresh token for an access token (+ id_token if openid scope).

Parameters

connection (Spatio.Connection): Connection to server
grant_type (String.t):
opts (keyword): Optional parameters
- :code (String.t): Required for authorization_code grant.
- :code_verifier (String.t): PKCE verifier — required for authorization_code grant.
- :redirect_uri (Uri):
- :refresh_token (String.t): Required for refresh_token grant.
- :client_id (String.t):
- :client_secret (String.t):

Returns

{:ok, Spatio.Model.TokenResponse.t} on success
{:error, Tesla.Env.t} on failure

post_user_info(connection, opts \\ [])

@spec post_user_info(
  Tesla.Env.client(),
  keyword()
) :: {:ok, Spatio.Model.UserInfoResponse.t()} | {:error, Tesla.Env.t()}

Same as GET /oauth2/userinfo. Provided for clients that send the bearer in the body.

Parameters

connection (Spatio.Connection): Connection to server
opts (keyword): Optional parameters

Returns

{:ok, Spatio.Model.UserInfoResponse.t} on success
{:error, Tesla.Env.t} on failure

register_o_auth_client(connection, client_registration_request, opts \\ [])

@spec register_o_auth_client(
  Tesla.Env.client(),
  Spatio.Model.ClientRegistrationRequest.t(),
  keyword()
) ::
  {:ok, nil}
  | {:ok, Spatio.Model.OAuthError.t()}
  | {:ok, Spatio.Model.ClientRegistrationResponse.t()}
  | {:error, Tesla.Env.t()}

Parameters

connection (Spatio.Connection): Connection to server
client_registration_request (ClientRegistrationRequest):
opts (keyword): Optional parameters

Returns

{:ok, Spatio.Model.ClientRegistrationResponse.t} on success
{:error, Tesla.Env.t} on failure