Nembl
Developer Guide
Authentication

Authentication

Nembl supports multiple authentication methods depending on the use case: API keys for server-to-server integrations, OAuth via Amazon Cognito for user-facing applications, and session tokens for browser-based access.

API Keys

API keys are the primary authentication method for programmatic access to the Nembl API.

Creating an API Key

  1. Navigate to Settings > Developer > API Keys.
  2. Click Create API Key.
  3. Configure the key:
    • Name -- a descriptive label (e.g., "CI/CD Pipeline", "Slack Integration").
    • Permissions -- select which API scopes the key can access. Options include:
      • services:read, services:write
      • requests:read, requests:write
      • workflows:read, workflows:write
      • users:read
      • audit:read
      • billing:read
    • Expiration -- optional expiration date. Keys without expiration remain valid until revoked.
  4. Click Create.
  5. Copy the key immediately. It is shown only once and cannot be retrieved later.
nmbl_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Using an API Key

Pass the key in the x-api-key header with every request:

curl -X GET https://api.nembl.com/v1/services \
  -H "x-api-key: nmbl_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Managing API Keys

From Settings > Developer > API Keys, you can:

  • View all active keys with their name, creation date, last used date, and permissions.
  • Revoke a key to immediately invalidate it. Revoked keys cannot be restored.
  • Rotate a key to generate a new value while preserving the name and permissions. The old key is revoked.

Key Prefixes

PrefixEnvironment
nmbl_live_Production
nmbl_test_Development/testing

Test keys can only access sandbox data and are rate-limited separately.

OAuth (Amazon Cognito)

For user-facing applications that need to act on behalf of a Nembl user, use OAuth 2.0 via Amazon Cognito.

OAuth Flow

Nembl uses the Authorization Code flow with PKCE:

  1. Redirect the user to the Nembl authorization endpoint:

    https://auth.nembl.com/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=openid profile email&
  code_challenge=PKCE_CHALLENGE&
  code_challenge_method=S256

  2. User logs in via the Nembl login page (Cognito hosted UI or custom).

  3. Receive the authorization code at your redirect URI:

    https://yourapp.com/callback?code=AUTH_CODE

  4. Exchange the code for tokens:

    curl -X POST https://auth.nembl.com/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&
      code=AUTH_CODE&
      client_id=YOUR_CLIENT_ID&
      redirect_uri=https://yourapp.com/callback&
      code_verifier=PKCE_VERIFIER"

  5. Use the access token in API requests:

    curl -X GET https://api.nembl.com/v1/services \
  -H "Authorization: Bearer eyJhbGciOi..."

Registering an OAuth Client

Contact Nembl support or use the Developer settings to register an OAuth client application. You will receive a client_id and configure your redirect_uri.

Session Tokens

Session tokens are used by the Nembl web application for browser-based authentication. They are managed automatically by the platform and are not intended for direct API use.

Session tokens are:

  • HttpOnly cookies -- not accessible via JavaScript.
  • Short-lived -- typically 1 hour, with automatic refresh.
  • Scoped -- tied to the user's session and company context.

Multi-Factor Authentication (MFA)

MFA adds a second verification step to user logins for increased security.

Enabling MFA for Your Account

  1. Navigate to Settings > Profile > Security.
  2. Click Enable MFA.
  3. Choose your method:
    • Authenticator app -- scan a QR code with Google Authenticator, Authy, or similar TOTP app.
    • SMS -- receive a verification code via text message (less secure, not recommended).
  4. Enter the verification code to confirm setup.
  5. Save the recovery codes in a secure location.

Enforcing MFA for All Members

Company admins can require MFA for all users:

  1. Navigate to Settings > Company > Security.
  2. Toggle Require MFA for all members.
  3. Users without MFA configured will be prompted to set it up at their next login.

MFA and API Keys

API keys bypass MFA because they are pre-authenticated credentials. Protect API keys with the same care as passwords. Use scoped permissions and expiration dates to limit risk.

Security Best Practices

  • Use scoped API keys. Grant only the permissions each integration actually needs.
  • Set expiration dates. Rotate keys regularly, especially for keys used in CI/CD pipelines.
  • Enable MFA for admins. At minimum, require MFA for users with Admin or Owner roles.
  • Use OAuth for user-facing apps. Do not embed API keys in client-side code. Use the OAuth flow instead.
  • Monitor key usage. Check the "last used" date on API keys and revoke any that are unused.
  • Store keys securely. Use Nembl Secrets or your own secrets manager. Never commit API keys to source control.
API ReferenceWebhooks