@widgetic/api-sdk

TypeScript/JavaScript client for the Widgetic API generated from OpenAPI. Works in browsers (ESM) and Node (CJS/ESM) using the Fetch API.

Usage

ES example:

// Import one of the APIs from api-sdk module
import { UsersApi } from '@widgetic/api-sdk';

// Static token copied from your account
const usersApi = new UsersApi('API_TOKEN');

// Ephemeral/rotating token (optional)
const usersEphemeral = new UsersApi({ apiKey: async () => getTokenFromYourApp() });

// Method use
const me = await usersApi.getCurrentUserProfile();

Authentication: API keys vs ephemeral tokens

• API key (recommended for most users):

  • Generate in the dashboard → API Keys page (Personal workspace or Team).
  • Click "Create Key", copy the value, and use it as shown above:
    • new UsersApi('API_TOKEN')
  • API keys are long‑lived until you revoke or rotate them in the same page.

• Ephemeral token (advanced, for your apps):

  • Short‑lived tokens issued by your backend/auth flow.
  • Provide a function that returns the current token; the SDK attaches it per request:
    • new UsersApi({ apiKey: async () => getTokenFromYourApp() })
  • Useful when you don’t want to expose a long‑lived key in the client.

Security tips:

• Keep tokens secret; never commit to source control.
• Rotate/revoke tokens from the API Keys page if leaked.

Supported environments

• Browsers with native fetch (ESM)
• Node.js 18+ (native fetch) or earlier Node with a fetch polyfill

Versioning

• Follows API releases. Breaking changes will be noted in release notes.

Authentication and access levels

Widgetic issues multiple API key types. The prefix determines the role:

• wgt_usr_… or wdg_org_… → role: user
• wgt_prt_… → role: partner
• wgt_adm_… → role: admin

Routes are annotated with an access level in the API (x-access-level):

• user: any authenticated user key can call (e.g., GET /users/me)
• partner: partner or admin keys only
• admin: admin keys only

Common auth errors and fixes:

• 401 Unauthorized: token missing/invalid/expired. Ensure Authorization: Bearer <token> is set. The SDK sets it automatically when you pass a token or async function.
• 403 Insufficient permissions: the key’s role can’t access this endpoint. Check prefix and use a key with higher privileges if appropriate.
• Local dev: ensure the API server is running at the expected BASE_PATH. For browser examples, override base path if needed when not using defaults.

Browser (ESM) example:

<script type="module">
  
  import { UsersApi } from '@widgetic/api-sdk';
  
  const usersApi = new UsersApi('API_TOKEN');
  
  const me = await usersApi.getCurrentUserProfile();
  console.log(me);
</script>

License

MIT © Widgetic