User

Authenticate

To begin, authentication requires you to generate your non-expiring Secret Key. The Secret Key uniquely identifies your account. It is used to generate temporary Bearer Tokens, which are required to authenticate all API requests.

Think of it as your private access token — it verifies your identity and authorizes the system to perform actions on your behalf, such as sending data, retrieving transcripts, or calling tools.

Generating secret key via interFace

You can generate your secret key by navigating to the "Manage Account" menu. This menu is accessible by clicking on your name in the top-right of the interface.

Click on "Generate" button and follow the instructions in the "secret key" section:

Obtaining the Bearer Token

This section describes how you can obtain an authentication Bearer Token.

The Bearer Token is a temporary access token used to authenticate your API requests.

• It is obtained by calling the /auth/token endpoint with your email address and Secret Key.
• The token is valid for 7 days.
• For security, tokens must be refreshed periodically.

Prerequisites

Before you can obtain an authentication bearer token, you must have the following:

• Email Address: The email address you used to generate your secret key.
• Secret Key: Your UNITH API secret key.

Steps

To obtain your authentication bearer token, use the /auth/token endpoint with the POST method.

• Endpoint: /auth/token
• Method: POST
• Description: Retrieves an authentication bearer token.
• Request Headers:
  • Accept: application/json
  • Content-Type: application/json
• Request Body:

{
  "email": "your_email_address",  // Replace with your registered email address
  "secretKey": "your_secret_key"     // Replace with your UNITH API secret key
}

• Request Parameters:
  • email (string, required): Your registered email address.
  • secretKey (string, required): Your UNITH API secret key.
• Request body:

curl -X 'POST' \
  'https://platform-api.unith.ai/auth/token' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "email": "your_email_address",
  "secretKey": "your_secret_key"
}'

Replace "your_email_address" and "your_secret_key" with your actual email address and secret key.

• Response:
  • Status Code: 200 (OK)
  • Response Body:

{
  "token": "your_authentication_bearer_token"  // The authentication bearer token.
}

• Response Parameters:
  • token (string): The authentication bearer token. This token must be included in the Authorization header of subsequent API requests.
• Expiration:
  • Bearer tokens expire after 7 days. Your application will need to obtain a new token after this period by repeating the process described above.
• Error Handling:
  • The API will return standard HTTP error codes for invalid requests.
  • 401 Unauthorized: Indicates that the email address or secret key is invalid.
  • 500 Internal Server Error: Indicates a server error.

Managing secret key via API

If you forgot your secret key, you need to follow these steps:

1. delete your existing secret key using /user/delete-secret-key

curl -X 'DELETE' \
  'https://platform-api.unith.ai/user/delete-secret-key' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 12345'

1. generate a new secret key using /user/generate-secret-key

curl -X 'PUT' \
  'https://platform-api.unith.ai/user/generate-secret-key' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer 12345'

Getting your user information (including organization ID)

In some steps you will need your user ID and/or your organization ID.

Use the following endpoint to get your information:

curl -X 'GET' \
  'https://platform-api.unith.ai/user/me' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer yourBearerToken'

Magic Link Authentication

UNITH supports passwordless authentication via magic links—secure, single-use login links sent to users' email addresses. This provides a simple and secure way to access the UNITH platform without managing passwords.

Magic links are automatically single-use and expire after 10 minutes for security. They cannot be reused, even if the link is clicked multiple times.

How Magic Link Authentication Works

1. Request Login Link: User enters their email address on the login page
2. Email Sent: UNITH sends an email containing a unique, time-limited login link
3. Click Link: User clicks the link in their email (valid for 10 minutes)
4. Automatic Login: User is automatically authenticated and redirected to the platform
5. Token Consumed: The login link becomes invalid immediately after first use

Security Features

Single-Use Tokens

• Each magic link can only be used once
• After successful login, the token is immediately invalidated
• Clicking the link again will show an "expired link" message

Time-Limited Validity

• Magic links expire after 10 minutes (30minutes for sign up)
• Unused links cannot be accessed after expiration
• For security, always use the most recent link sent to your email

Secure Token Generation

• Tokens use cryptographically secure random generation
• Each token is unique and cannot be predicted or guessed
• Tokens are tied to specific user accounts and cannot be transferred

Common Scenarios

Expired Link

Issue: "Link expired" message appears when clicking the magic link.

Cause: The link was either:

• Sent more than 10 minutes ago
• Already used to log in

Solution: Request a new magic link from the login page.

Already Used Link

Issue: Clicking the magic link shows an error or expired message.

Cause: The link was already used to authenticate. Each link works only once.

Solution:

• If you're already logged in, no action needed
• If you need to log in again, request a new magic link

Page Refresh After Login

Behavior: After clicking a magic link and logging in, the authentication token is automatically removed from the URL.

Why: This prevents the single-use token from appearing in browser history or bookmarks.

Note: Refreshing the page after login will not cause errors—you'll remain authenticated via your session.

Multiple Browser Tabs

Scenario: You click a magic link that opens in a new tab while you already have UNITH open in another tab.

Behavior:

• The new tab authenticates successfully with the magic link
• Other tabs check authentication state and update automatically
• No errors or conflicts occur

Best Practices

Email Access

• Ensure you have access to the email address registered with your UNITH account
• Check spam/junk folders if magic link emails don't appear in your inbox
• Add UNITH's email sender to your contacts to ensure delivery

Timing

• Use magic links within 10 minutes of receiving them
• Request a new link if the previous one expired
• Only one magic link is valid at a time—newer links invalidate older ones

Security

• Don't share magic links with others
• Magic links are tied to your specific account and should never be forwarded
• Links in email can only be used from the recipient's account

Browser Compatibility

• Magic links work in all modern browsers
• No special browser settings or extensions required
• Works on mobile and desktop devices

Important Notes

Token Expiration: Magic links expire 10 minutes after being sent. Always use the link promptly after receiving the email.

Single Use Only: Each magic link can only be used once. After successful authentication, the link becomes permanently invalid.

Email Requirement: You must have access to the email address registered with your UNITH account to use magic link authentication.

Session Duration: After logging in via magic link, your session follows standard UNITH session expiration policies (separate from the magic link's 10-minute validity).

Multiple Requests: If you request multiple magic links, only the most recent one will work. Previous links are automatically invalidated when a new one is generated.

No Password Required: Magic links eliminate the need to remember passwords, but you should still maintain access to your registered email account.

Alternative Authentication Methods

If you prefer not to use magic links, UNITH also supports:

• Google OAuth: Sign in with your Google account
• API Authentication: Use Secret Keys and Bearer Tokens for programmatic access