Authentication

Overview

The Simply360 API supports three primary authentication methods. All three use the standard Authorization: Bearer <token> header. (MCP clients can also connect with OAuth 2.0 — see MCP Server.)

Authorization: Bearer <token>

Credentials are environment-specific. Create and use each API key, session token, OAuth client, or first-party session only in its matching production, Staging, or Development environment. See Environments before configuring a non-production client.

Authentication Methods

Method	Token Format	Use Case	Lifetime
API Key	s360_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx	Server-to-server integrations, backend services, scheduled jobs	Until revoked or expired
Session Token	s360_sess_xxxxxxxxxxxxxxxxxxxxxxxxxxxx	Short-lived scoped access — AI agents, browser proxying, partner access	Maximum 24 hours
Cognito JWT	Standard JWT	First-party Simply360 webapp and internal tools	1 hour by default (auto-refreshed by Cognito)

API Keys

API keys are long-lived credentials tied to a specific team. Use them for server-side integrations where you can keep the key secret. Every API key starts with the prefix s360_live_.

An API key has two permission layers: featurePermissions controls which feature/admin API areas the key can call, while teamRoleSimplyId selects the Team Role whose data permissions control record and MCP access. A key without a data role can authenticate and use its allowed non-data feature routes, but it cannot read or write team records. A full-data key must point at a Team Role that grants DATA_FULL_ACCESS; write access additionally requires that role grant to be edit-level.

Creating API Keys (Dashboard)

1. Log into your Simply360 workspace.
2. Navigate to Team Administration → API Keys.
3. Click Create API Key.
4. Give the key a descriptive name (e.g., "CRM Sync Production").
5. Configure the key's Team Role (data access), feature permissions, allowed IP addresses, and optional expiration date as needed.
6. Click Create and copy the full key immediately. The full value is only returned once.

Creating API Keys (API)

You can also create API keys programmatically. API key management endpoints require the TEAM_ADMIN_API_KEYS feature permission, and assigning a Team Role to a key (teamRoleSimplyId) additionally requires a Team Admin or system administrator, or a credential with edit access to TEAM_ADMIN_USER_ROLES. In practice, use an authenticated admin user's token:

TypeScript SDK

import { Simply360 } from '@simply360/sdk';

const s360 = new Simply360({
  getToken: async () => process.env.S360_USER_ACCESS_TOKEN!,
  teamSimplyId: process.env.S360_TEAM_SIMPLY_ID!,
});

const result = await s360.apiKeys.create({
  name: 'CRM Sync Production',
  teamRoleSimplyId: 'TROL-0000-0001',
  featurePermissions: ['TEAM_ADMIN_DC_SCHEMA'],
});

// The full key is in result.data.fullApiKey — store it now, it will not be shown again.
console.log(`Key: ${result.data.fullApiKey}`);

cURL

curl -s -X POST "https://api.simply360.app/v1/api-keys" \
  -H "Authorization: Bearer $S360_USER_ACCESS_TOKEN" \
  -H "X-Team-Id: $S360_TEAM_SIMPLY_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Sync Production",
    "teamRoleSimplyId": "TROL-0000-0001",
    "featurePermissions": ["TEAM_ADMIN_DC_SCHEMA"]
  }' | jq '{id: .data.id, fullApiKey: .data.fullApiKey}'

Using an API Key

import { Simply360 } from '@simply360/sdk';

const s360 = new Simply360({
  apiKey: process.env.S360_API_KEY!, // s360_live_...
});

const records = await s360.dataRecords.list({ dataCollectionSimplyId: 'XXXX-XXXX-XXXX' });

curl -s "https://api.simply360.app/v1/data-records?dataCollectionSimplyId=XXXX-XXXX-XXXX" \
  -H "Authorization: Bearer s360_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

API Key Best Practices

• Store API keys in environment variables or a secrets manager. Never commit them to source control.
• Apply least privilege — choose the narrowest Team Role data permissions and feature permissions the integration actually needs.
• Give each integration its own key so you can revoke access independently.
• Rotate keys periodically using the POST /v1/api-keys/{apiKeySimplyId}/rotate endpoint.
• Restrict keys to specific source IP addresses where possible using the allowedIpAddresses setting.

Session Tokens

Session tokens are short-lived, scoped credentials that you mint from your server using an API key. They are ideal for granting controlled access to browsers, mobile apps, AI agents, and third-party partners without exposing your long-lived API key. Every session token starts with s360_sess_ and has a maximum lifetime of 24 hours (1440 minutes).

Creating a Session Token

TypeScript SDK

const session = await s360.sessionTokens.create({
  expiresInMinutes: 60,
  featurePermissions: ['TEAM_ADMIN_DC_SCHEMA'],
  oauthScopes: ['schema:read', 'records:read'],
});

// session.data.token is the s360_sess_... value to send to the client.
console.log(`Token: ${session.data.token}`);
console.log(`Expires at: ${session.data.expiresAt}`);

cURL

curl -s -X POST "https://api.simply360.app/v1/session-tokens" \
  -H "Authorization: Bearer $S360_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresInMinutes": 60,
    "featurePermissions": ["TEAM_ADMIN_DC_SCHEMA"],
    "oauthScopes": ["schema:read", "records:read"]
  }' | jq '{token: .data.token, expiresAt: .data.expiresAt, oauthScopes: .data.oauthScopes}'

If oauthScopes is omitted, the token defaults to read-only API scopes: schema:read and records:read. Request records:write only for agents or clients that need to create, update, or archive records. Session tokens inherit the parent API key's Team Role data permissions and can only narrow the parent key's feature permissions and scopes.

Session Token Properties

Property	Type	Description
expiresInMinutes	integer	Lifetime in minutes. Defaults to 60; maximum is 1440 (24 hours).
featurePermissions	string[]	Array of feature permissions. Cannot exceed the parent API key's permissions.
oauthScopes	string[]	API scopes applied to public REST and MCP access. Defaults to schema:read and records:read.

Use Cases

• Browser proxying — Issue a short-lived, read-only token to a browser client so it can fetch data directly without exposing your API key.
• Third-party access — Grant a partner temporary, scoped access.
• AI agents — Give an LLM-driven workflow tightly scoped credentials it cannot exceed.

Cognito JWT

Cognito JWT authentication is used by the Simply360 web application and other first-party clients. It relies on AWS Cognito for identity management and token issuance.

Usage

When authenticating with a Cognito JWT, you must also identify the team context for the request — provide the X-Team-Id header (or a teamSimplyId query parameter).

const response = await fetch('https://api.simply360.app/v1/data-records?dataCollectionSimplyId=XXXX-XXXX-XXXX', {
  headers: {
    Authorization: `Bearer ${cognitoIdToken}`,
    'X-Team-Id': teamSimplyId,
    'Content-Type': 'application/json',
  },
});

If you are using the SDK with a dynamic identity (e.g. a Cognito session whose token refreshes), pass getToken instead of apiKey:

const s360 = new Simply360({
  getToken: async () => await getFreshCognitoIdToken(),
  teamSimplyId,
});

Important Notes

• Cognito JWTs expire after one hour by default. The Cognito SDK handles automatic token refresh.
• The X-Team-Id header (or teamSimplyId query parameter) is required for Cognito JWT requests so the API knows which team to operate against.
• This method is intended for first-party applications. For third-party integrations, use API keys or session tokens.

Choosing an Authentication Method

Scenario	Recommended
Backend service or cron job	API Key
CI/CD pipeline	API Key
Browser-based client fetching data	Session Token
Temporary third-party access	Session Token
AI agent / autonomous workflow	Session Token
Simply360 web app or first-party tools	Cognito JWT
MCP server integration	OAuth 2.0 (or a scoped API key)

Security Recommendations

• Never expose API keys in client-side code, public repositories, or browser network requests.
• Use session tokens with the shortest practical lifetime when granting access to frontends or third parties.
• Scope session tokens to only the feature permissions and scopes they actually need.
• Monitor your Team Administration → API Keys page for unused or suspicious keys and revoke them promptly.
• All API requests must be made over HTTPS. Plain HTTP is rejected.