Skip to main content

OAuth 2.0 Authentication

Use OAuth 2.0 authorization code flow with PKCE to access user portfolio data with their consent.

Endpoints​

EndpointURL
Authorizationhttps://oauth.kryptos.io/oidc/auth
Tokenhttps://oauth.kryptos.io/oidc/token
UserInfohttps://oauth.kryptos.io/oidc/userinfo
Revocationhttps://oauth.kryptos.io/oidc/token/revocation
Introspectionhttps://oauth.kryptos.io/oidc/token/introspection
Discoveryhttps://oauth.kryptos.io/oidc/.well-known/openid_configuration
JWKShttps://oauth.kryptos.io/oidc/jwks

Available Scopes​

Core Scopes​

ScopeDescription
openidBasic OpenID Connect access (required)
profileUser profile (name, preferred_username, language, transaction_limit)
emailEmail address and verified status
offline_accessAllow refresh tokens for offline data access

Data Scopes (Granular Read/Write)​

ResourceRead ScopeWrite ScopeDescription
Portfoliosportfolios:readportfolios:writeHoldings, DeFi, NFTs, balances
Transactionstransactions:readtransactions:writeTransactions, ledgers, labels, spam
Integrationsintegrations:readintegrations:writeConnected wallets, exchanges, sync, CSV
Contactscontacts:readcontacts:writeContacts and counterparties
Taxtax:readtax:writeTax calculations and reports
Accountingaccounting:readaccounting:writeAccounting ledger entries
Reportsreports:readreports:writeGenerated reports and exports
Invoicesinvoices:readinvoices:writeInvoicing
Swapsswaps:readswaps:writeSwaps
Workspaceworkspace:readworkspace:writeWorkspace settings and configuration
Usersusers:readusers:writeUser profile and preferences
Not all scopes are in the default client set

Write scopes, and contacts, invoices and swaps in either direction, are not in the default client scope set below. Requesting one in the authorization request is not enough — your client has to be registered with it, via the scope picker in the Developer Portal when you create the client, or by asking support to widen an existing one. Until then /v1/contacts and /v1/counter-parties return 403 insufficient_scope.

A grant can never exceed what the consenting member's role allows, so a member with a limited role may produce a narrower grant than you requested. Read the scope value returned with the token and degrade gracefully rather than assuming you received everything you asked for.

Authorization Flow​

Step 1: Register Your Client​

Register your application on the Developer Portal to receive:

  • client_id
  • client_secret
  • Default scopes assigned to your client

Default Client Scopes:

openid profile offline_access email portfolios:read transactions:read
integrations:read tax:read accounting:read reports:read workspace:read users:read
info

More granular scope controls will be added in the future. For custom scope requirements, contact [email protected]

Step 2: Generate PKCE Parameters​

PKCE (Proof Key for Code Exchange) adds security to the authorization flow, protecting against code interception attacks.

// Generate code verifier (random string 43-128 chars)
function generateCodeVerifier() {
  const array = new Uint8Array(32);
  crypto.getRandomValues(array);
  return base64UrlEncode(array);
}

// Generate code challenge (SHA-256 hash of verifier)
async function generateCodeChallenge(verifier) {
  const encoder = new TextEncoder();
  const data = encoder.encode(verifier);
  const hash = await crypto.subtle.digest("SHA-256", data);
  return base64UrlEncode(new Uint8Array(hash));
}

function base64UrlEncode(buffer) {
  return btoa(String.fromCharCode(...buffer))
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=+$/, "");
}
ParameterDescription
code_verifierRandom string (43-128 chars) sent during token exchange
code_challengeBase64url encoded SHA-256 hash of the code verifier
code_challenge_methodAlways S256 for SHA-256

Step 3: Redirect to Authorization​

Redirect the user to the authorization endpoint:

GET https://oauth.kryptos.io/oidc/auth?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_REDIRECT_URI&
  scope=openid profile email portfolios:read transactions:read integrations:read offline_access&
  state=RANDOM_STATE&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256

Example Scope Combinations:

  • Read-only: openid profile portfolios:read transactions:read
  • Full access: openid profile portfolios:read portfolios:write transactions:read transactions:write
ParameterRequiredDescription
response_typeYesAlways code
client_idYesYour client ID
redirect_uriYesYour callback URL
scopeYesSpace-separated list of scopes
stateYesRandom string to prevent CSRF attacks
code_challengeYesPKCE code challenge
code_challenge_methodYesAlways S256

Step 4: Exchange Code for Token​

After the user authorizes, they're redirected to your redirect_uri with an authorization code. Exchange it for tokens:

curl -X POST https://oauth.kryptos.io/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=CODE_VERIFIER"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 86400,
  "refresh_token": "def50200...",
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "scope": "openid profile portfolios:read transactions:read"
}
Token Lifetimes
  • Access Token: 24 hours
  • Refresh Token: 30 days
  • ID Token: 24 hours
  • Authorization Code: 10 minutes

Step 5: Call APIs​

Use the access token to call APIs:

curl -X GET https://api-v2.kryptos.io/v1/holdings \
  -H "Authorization: Bearer ACCESS_TOKEN"

Required Headers​

HeaderDescription
AuthorizationBearer {access_token}

That is the only header data calls need. X-Client-Id and X-Client-Secret were required by the previous API and are no longer used — see Migrating from the previous API. Client credentials are still required on the OIDC token endpoint itself, as shown above.

Code Examples​

class KryptosClient {
  constructor(clientId, clientSecret) {
    this.clientId = clientId;
    this.clientSecret = clientSecret;
    this.oauthUrl = "https://oauth.kryptos.io";
    this.apiUrl = "https://api-v2.kryptos.io";
    this.accessToken = null;
  }

  // Generate PKCE parameters
  async generatePKCE() {
    const array = new Uint8Array(32);
    crypto.getRandomValues(array);
    const verifier = this.base64UrlEncode(array);

    const encoder = new TextEncoder();
    const data = encoder.encode(verifier);
    const hash = await crypto.subtle.digest("SHA-256", data);
    const challenge = this.base64UrlEncode(new Uint8Array(hash));

    return { verifier, challenge };
  }

  base64UrlEncode(buffer) {
    return btoa(String.fromCharCode(...buffer))
      .replace(/\+/g, "-")
      .replace(/\//g, "_")
      .replace(/=+$/, "");
  }

  // Get authorization URL
  // Scopes use granular :read and :write format
  getAuthUrl(
    redirectUri,
    codeChallenge,
    scopes = [
      "openid", // Required - basic OIDC
      "profile", // Read: name, picture
      "email", // Read: email address
      "portfolios:read", // Read: portfolio holdings
      "transactions:read", // Read: transaction history
      "integrations:read", // Read: connected wallets/exchanges
      "offline_access", // Enable refresh tokens
    ]
  ) {
    const params = new URLSearchParams({
      response_type: "code",
      client_id: this.clientId,
      redirect_uri: redirectUri,
      scope: scopes.join(" "),
      state: Math.random().toString(36).substring(7),
      code_challenge: codeChallenge,
      code_challenge_method: "S256",
    });
    return `${this.oauthUrl}/oidc/auth?${params}`;
  }

  // Exchange authorization code for tokens
  async exchangeCode(code, redirectUri, codeVerifier) {
    const response = await fetch(`${this.oauthUrl}/oidc/token`, {
      method: "POST",
      headers: { "Content-Type": "application/x-www-form-urlencoded" },
      body: new URLSearchParams({
        grant_type: "authorization_code",
        code,
        redirect_uri: redirectUri,
        client_id: this.clientId,
        client_secret: this.clientSecret,
        code_verifier: codeVerifier,
      }),
    });

    const tokens = await response.json();
    this.accessToken = tokens.access_token;
    return tokens;
  }

  // Get user holdings
  async getHoldings() {
    const response = await fetch(`${this.apiUrl}/v1/holdings`, {
      headers: { Authorization: `Bearer ${this.accessToken}` },
    });
    return response.json();
  }

  // Get user info
  async getUserInfo() {
    const response = await fetch(`${this.apiUrl}/v1/users/me`, {
      headers: { Authorization: `Bearer ${this.accessToken}` },
    });
    return response.json();
  }
}

// Usage
const client = new KryptosClient("your_client_id", "your_client_secret");

// 1. Generate PKCE and redirect user
const { verifier, challenge } = await client.generatePKCE();
sessionStorage.setItem("code_verifier", verifier);
window.location.href = client.getAuthUrl(
  "http://localhost:3000/callback",
  challenge
);

// 2. Handle callback
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get("code");
const storedVerifier = sessionStorage.getItem("code_verifier");
await client.exchangeCode(
  code,
  "http://localhost:3000/callback",
  storedVerifier
);

// 3. Get data
const holdings = await client.getHoldings();

Token Refresh​

Access tokens expire after 24 hours. Use refresh tokens to get new ones:

curl -X POST https://oauth.kryptos.io/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "refresh_token=YOUR_REFRESH_TOKEN"

Token Revocation​

Revoke tokens when user logs out:

curl -X POST https://oauth.kryptos.io/oidc/token/revocation \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "token=TOKEN_TO_REVOKE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

UserInfo Endpoint​

Get user information using access token:

curl -X GET https://oauth.kryptos.io/oidc/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Response:

{
  "sub": "user_9f2c8a",
  "name": "John Doe",
  "picture": "https://example.com/avatar.jpg",
  "updated_at": 1642248600,
  "email": "[email protected]",
  "email_verified": true
}

Claims are returned only for the scopes you were granted: name, picture and updated_at require profile; email and email_verified require email. sub is always present and is the user's stable id — the same value GET /v1/users/me returns as uid.

userinfo does not report which scopes you hold. Read the scope value returned with the access token instead. (Earlier documentation showed portfolios_access-style booleans here; they were never populated and are gone.)

Access token claims​

Beyond the standard OIDC claims, the access token itself carries the workspace the grant is bound to:

ClaimDescription
workspaceIdWorkspace this token can access
workspaceNameIts display name
workspaceTypeWorkspace type
roleThe granting member's role, which bounds the scopes
planActive plan name, when the workspace has one

Because the workspace is in the token, data calls omit the workspace parameter entirely — see Workspaces. Inspect these claims with the introspection endpoint.

Error Handling​

OIDC Error Codes​

Error CodeDescription
invalid_requestRequest is missing required parameter
invalid_clientClient authentication failed
invalid_grantAuthorization grant is invalid or expired
unauthorized_clientClient not authorized for this grant type
unsupported_grant_typeGrant type not supported
invalid_scopeRequested scope is invalid
access_deniedUser denied authorization
invalid_tokenToken is invalid or expired

Error Handling Example​

async function makeApiCall(endpoint, accessToken, refreshToken) {
  const response = await fetch(endpoint, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });

  if (response.status === 401) {
    // Token expired - try refresh
    const newTokens = await refreshAccessToken(refreshToken);
    return makeApiCall(
      endpoint,
      newTokens.access_token,
      newTokens.refresh_token
    );
  }

  if (response.status === 403) {
    // Insufficient scope
    throw new Error("Insufficient permissions for this resource");
  }

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error} - ${error.error_description}`);
  }

  return response.json();
}

Security Best Practices​

  1. Always use PKCE - Protects against authorization code interception
  2. Store secrets securely - Never expose client secrets in frontend code
  3. Use HTTPS - Always use secure connections
  4. Validate state parameter - Prevent CSRF attacks
  5. Handle token expiration - Implement refresh token logic
  6. Request minimal scopes - Only request necessary permissions

Token Response​

FieldDescription
access_tokenJWT token for API authentication
id_tokenOIDC ID token with user claims
token_typeAlways Bearer
expires_inToken validity in seconds (86400 = 24hrs)
refresh_tokenToken for obtaining new access tokens
scopeGranted scopes

Rate Limits​

Endpoint TypeLimitWindow
Token Endpoint100 requestsper minute
UserInfo Endpoint1000 requestsper hour
Other OIDC200 requestsper hour

Rate limits are per client ID. Exceeding limits returns HTTP 429 with retry_after header.