Authentication

Segmind Cloud Authentication Documentation

Overview

This document details the authentication methods supported by Segmind Platform:

• OAuth 2.0 social login (Google, Microsoft, Discord)
• Bearer token authentication using JWT
• API key authentication for server-to-server communication

Social logins provide a seamless and secure authentication experience by leveraging existing accounts from trusted providers, eliminating the need for users to create and remember additional credentials.

JSON Web Tokens (JWT) are compact, URL-safe tokens that enable secure information transmission between parties, containing encoded JSON payloads that can include user data and permissions.

Which host to call

Three origins are involved, and they are not interchangeable. Sending an account or auth request to the console origin is the most common cause of an unexpected 404.

OAuth Authentication

Supported Providers and Scopes

Signing in to the console

Sign-in is protected by an invisible verification check. Each attempt uses its own single-use token, so retrying a failed sign-in always starts a fresh check.

Notices you might see

Failures appear as a short message inside the card rather than on a separate error page.

OAuth Login Process

1. Redirect users to our OAuth login page:

https://platform.segmind.com/auth/login

2. Choosing a provider sends the browser to the authorization endpoint for that provider, where {provider} is google, discord or azure (Microsoft):

https://cloud.segmind.com/api/login/{provider}

3. The provider authenticates the user and returns them to Segmind, which then redirects the browser back to the console:

https://platform.segmind.com/auth/callback

4. The session is established as an HTTP-only secure cookie. The browser navigation itself returns no token body — to read the session, call:

curl "https://cloud.segmind.com/api/auth/profile" \
  --cookie "your-session-cookie"

which responds with:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "username": "Ada Lovelace",
  "email": "you@example.com"
}

Because the session lives in a cookie rather than a redirect fragment, there is no token to capture from the callback URL.

Signing in with an email link

Alongside the three providers, an account can sign in with a one-time link sent by email — the Continue with Email option on the sign-in page.

curl -X POST "https://cloud.segmind.com/api/auth/login/email/request" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "token": "<verification token>"
  }'

A successful request responds with a message, by default "Check your email for the login link". The emailed link is single-use. A failure responds with error or message, by default "Failed to send login email".

Bearer Token Authentication

Using Bearer Tokens

Include the JWT token in your API requests using the Authorization header:

curl -X GET "https://cloud.segmind.com/api/auth/profile" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Format

Our JWTs include:

• jti: Unique identifier for the JWT
• exp: Token expiration timestamp
• iat: Token issue timestamp
• nbf: Token not valid before timestamp
• identity: Email of the token user

Token Renewal

To refresh an expired access token:

curl -X POST "https://cloud.segmind.com/api/auth/refresh-token" \
  -H "Authorization: Bearer {refresh_token}"

API Key Authentication

Overview

API keys provide server-to-server authentication for automated workflows. Include them in the x-api-key request header.

API Key Format

• Prefix: SG_ on every key
• Followed by 16 hexadecimal characters, so a key is 19 characters in total
• Example shape: SG_0123456789abcdef

Using API Keys

Include the API key in your requests:

curl "https://api.segmind.com/v1/get-user-credits" \
  -H "x-api-key: YOUR_API_KEY"

That endpoint returns your credit balance and is the cheapest way to confirm a key works — it runs no model and costs nothing. See Account and Billing APIs.

API Key Management

These are the calls the console itself makes on the API Keys page. They authenticate as your signed-in session, not with an API key, so the console is usually the easier way to manage keys. For server-to-server work, call the AI Gateway with x-api-key instead.

List your keys:

curl "https://cloud.segmind.com/api/auth/get-api-keys" \
  -H "Authorization: Bearer {your_access_token}"

Generate a new API key. token is the sign-in page's verification token, which is why key creation is a console action rather than an automatable one. name and expiry_date are optional:

curl -X POST "https://cloud.segmind.com/api/auth/generate-api-key" \
  -H "Authorization: Bearer {your_access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "<verification token>",
    "name": "Production API Key"
  }'

Rename a key:

curl -X PUT "https://cloud.segmind.com/api/auth/rename-api-key" \
  -H "Authorization: Bearer {your_access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "SG_0123456789abcdef", "name": "Staging key" }'

Restrict which models a key may call. Send model_access even when it is null, which clears the restriction — omitting the field is rejected rather than treated as "unrestricted":

curl -X PUT "https://cloud.segmind.com/api/auth/api-key-model-access" \
  -H "Authorization: Bearer {your_access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "SG_0123456789abcdef", "model_access": null }'

A 200 confirms the policy is live. A 202 means it was saved but the gateway is still serving the previous policy until the key is next re-authenticated — read the cache_purged flag rather than treating any 2xx as done.

Revoke an API key. The key travels in the body, not the path:

curl -X DELETE "https://cloud.segmind.com/api/auth/delete-api-key" \
  -H "Authorization: Bearer {your_access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "api_key": "SG_0123456789abcdef" }'

Security Guidelines

Token Lifecycle

• Access tokens expire after 1 hour
• Refresh tokens expire after 30 days
• API keys don't expire but should be rotated regularly

Rate Limits

• Authentication endpoints: 5 requests/minute per IP
• Token refresh: 10 requests/hour per user
• API endpoints: Varies by subscription tier

Best Practices while using the platform

1. Secure Storage
   • Never expose API keys in client-side code
   • Use environment variables for key storage
   • Rotate API keys periodically
2. Error Handling
   • Implement retry logic with exponential backoff
   • Handle token expiration gracefully
   • Watch for unexpected activity in Cost Analytics, which can filter by API key and break spend down per key, and in Generations, which lists every request made from the workspace. See Monitoring.

Error Responses

Common authentication errors:

{
  "error": "invalid_token",
  "error_description": "Token has expired",
  "status_code": 401
}

Code Examples

Python

import requests

class SegmindClient:
    """Calls the AI Gateway with an API key — the path to use for
    server-to-server work."""

    def __init__(self, api_key):
        self.base_url = "https://api.segmind.com/v1"
        self.headers = {"x-api-key": api_key}

    def get_credits(self):
        """Cheapest way to confirm a key works: runs no model, costs nothing."""
        response = requests.get(
            f"{self.base_url}/get-user-credits",
            headers=self.headers
        )
        response.raise_for_status()
        return response.json()

Node.js

const axios = require('axios');

class SegmindClient {
  constructor({ apiKey }) {
    this.baseUrl = 'https://api.segmind.com/v1';
    this.headers = {
      'Content-Type': 'application/json',
      'x-api-key': apiKey,
    };
  }

  // Cheapest way to confirm a key works: runs no model, costs nothing.
  async getCredits() {
    const response = await axios.get(`${this.baseUrl}/get-user-credits`, {
      headers: this.headers,
    });
    return response.data;
  }
}

Support

For authentication issues or questions:

• Email: support@segmind.com
• Documentation: https://docs.segmind.com
• Status page: https://status.segmind.com