Authentication

Applications authenticate by exchanging client credentials for a short-lived, signed access token, then presenting that token as a bearer token on every API call. The credentials never travel on individual requests; only the short-lived token does.

httpPOST /v1/oauth/token HTTP/1.1
Host: api.gravitasetrm.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id=svc-risk-etl
&client_secret=***
&scope=positions:read valuations:read

jsonHTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6...",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "positions:read valuations:read"
}

Present the token in the Authorization header on every call. When it expires (typically minutes, not hours) request a new one. An SDK does this refresh for you automatically.

pythonimport time, requests

class TokenProvider:
    def __init__(self, client_id, secret):
        self.client_id, self.secret = client_id, secret
        self._token, self._exp = None, 0

    def bearer(self):
        if time.time() > self._exp - 30:          # refresh before expiry
            r = requests.post("https://api.gravitasetrm.com/v1/oauth/token", data={
                "grant_type": "client_credentials",
                "client_id": self.client_id, "client_secret": self.secret,
                "scope": "positions:read valuations:read"})
            body = r.json()
            self._token = body["access_token"]
            self._exp = time.time() + body["expires_in"]
        return self._token

Tokens are scoped to least privilege, an integration receives only the access it needs. Because tokens are short-lived and signed, a leaked token has a limited blast radius and a short lifetime.

Beyond authentication (who you are), authorization (what you may do) is enforced by the same role and permission model used in administration, so API access respects the same governance as the UI. There is no privileged API back door; a service account is subject to the same rules as a human user with the same role.

Verify the token signature and expiry on every request; never trust an unsigned or expired token. The signature is what proves the token was issued by Gravitas and not forged.