When integrating with the Cloud Factory platform, understanding how authentication works is essential. Whether you're building a custom workflow or connecting your systems, secure and proper credential management will keep your data safe and your integrations running smoothly. This guide walks you through everything you need to know about authenticating API requests, managing tokens, and implementing security best practices.

How Cloud Factory Authentication Works

At the core of our API security is a trust-based system built on industry-standard practices. Cloud Factory uses Auth0, a leading third-party authentication provider, to verify your identity and issue the credentials you'll use for every API request.

Here's the basic flow:

When you log in through Auth0, the system authenticates your credentials and issues an access token. This token travels with every API call you make. Our servers validate this token and cross-reference it with your account permissions in our authorization system. This two-layer approach ensures that only authenticated users with proper permissions can access platform resources.

This separation of concerns—authentication handled by Auth0, authorization managed internally—provides robust security while keeping the process straightforward for developers.

Understanding Token Types

Cloud Factory uses two types of tokens, each serving a different purpose in your authentication workflow.

Access Tokens: Short-Lived & Secure

An access token is your temporary credentials for making API requests. Think of it as a time-limited badge that grants you access to protected resources.

Key characteristics:

  • Valid for a limited time window (displayed when generated)
  • Required for every API request
  • Automatically validated on each call
  • Ideal for short-lived operations or testing

Access tokens are the safest choice when you only need API access for a short period or are experimenting in the Swagger UI.

Refresh Tokens: Your API Keys

A refresh token (also called an API key) is a long-lived credential that can generate new access tokens. Unlike an access token, a refresh token doesn't expire quickly and can be used repeatedly.

Critical security points:

  • Treated as equivalent to a username-password login
  • Grants full account impersonation if compromised
  • The audit system cannot distinguish between a username-password login and a refresh token login
  • If compromised, an unauthorized user has complete access to your account

This is why refresh token security is paramount. Store them securely, never commit them to version control, and treat them with the same care as a password.

Getting Your Refresh Token (API Key)

Follow these steps to obtain your refresh token. You can use either the API directly or the Swagger UI.

Step 1: Trigger the Login Endpoint

Make a request to the /Authenticate/Login endpoint. This generates a unique authorization URL.

Step 2: Visit the Generated URL

Copy the full URL from the endpoint response and open it in your browser. You'll be redirected back automatically after authentication.

Step 3: Copy Your Refresh Token

On the page that loads, locate the "Refresh Token" field. This string is approximately 45 characters long. Copy it and store it securely.

Pro tip: If you only need API access for an hour or less, or you're just testing in Swagger, you can skip the refresh token and use the access token instead. Click one of the padlock icons in Swagger, paste the access token, and you're authenticated temporarily without storing a long-term credential.

Exchanging a Refresh Token for an Access Token

Once you have your refresh token, you need to exchange it for an access token before making API requests. This is a simple process.

The Exchange Process

Use the /Authenticate/ExchangeRefreshToken/{token} endpoint, replacing {token} with your refresh token.

The endpoint returns:

  • A valid access token (ready to use)
  • An expiration time (in seconds or milliseconds, depending on API documentation)

Best Practices for Token Management

Don't generate a new access token for every request. This is a common mistake that significantly slows down your application and creates unnecessary load.

Instead:

  • Generate an access token once
  • Reuse it for multiple requests until it approaches expiration
  • Implement a refresh mechanism before it expires
  • Store the expiration time and only generate a new token when needed

This approach improves performance and reduces unnecessary API calls.

Example Workflow

  1. Generate a refresh token and store it securely in your application configuration
  2. On application startup (or before the token expires), exchange the refresh token for an access token
  3. Use this access token for all API requests until expiration
  4. Before expiration, repeat step 2 with the same refresh token
  5. Never hardcode tokens in your code; use environment variables or secure configuration managers

Revoking Tokens When No Longer Needed

If you're retiring an integration, switching to a new API key, or need to invalidate credentials for any reason, you can revoke a refresh token immediately.

Use the /Authenticate/RevokeToken/{refreshtoken} endpoint, replacing {refreshtoken} with the token you want to revoke.

Once revoked:

  • The refresh token can no longer generate new access tokens
  • Any active access tokens derived from it will continue working until their natural expiration
  • The token cannot be restored; you'll need to generate a new one

Revoking is useful for:

  • Decommissioning old integrations
  • Responding to potential security breaches
  • Rotating credentials on a schedule
  • Cleaning up unused API keys

Security Considerations & Incident Response

Protecting Your Tokens

Your refresh token is equivalent to your password. Treat it accordingly:

  • Store securely: Use environment variables, secure vaults, or configuration management systems—never hardcode in source code
  • Limit exposure: Share only with your team members who genuinely need it
  • Don't log tokens: Ensure your logging systems don't accidentally record credentials
  • Use in secure channels: Only transmit over encrypted connections (HTTPS)
  • Rotate periodically: Generate new tokens on a regular schedule

If Your Refresh Token Is Compromised

If you suspect a refresh token has been exposed or misused:

  1. Contact Cloud Factory immediately via your support channel
  2. Revoke the token right away using the revoke endpoint
  3. Generate a new refresh token for continued operations
  4. Monitor your account for unauthorized activity
  5. Update your audit logs with incident details

This is critical: Failing to report a compromised refresh token to Cloud Factory may result in audit complications or security issues down the road. Our team helps trace the scope of exposure and confirm that no unauthorized changes occurred.

Next Steps

Now that you understand Cloud Factory's authentication system, you're ready to:

  • Explore our comprehensive Platform API documentation
  • Build secure integrations that handle tokens properly
  • Implement token refresh logic in your applications
  • Set up monitoring and alerting for token expiration

For detailed API endpoint documentation, authentication troubleshooting, or questions about token management in your specific use case, visit our Platform API documentation or reach out to our Partner Care team.

TL;DR

  • Cloud Factory uses Auth0 for authentication and issues two token types: access tokens (short-lived) and refresh tokens (long-lived API keys)
  • Access tokens authenticate individual requests; refresh tokens generate new access tokens and should be treated like passwords
  • Get a refresh token via /Authenticate/Login, exchange it for an access token via /Authenticate/ExchangeRefreshToken/{token}
  • Reuse access tokens for multiple requests instead of generating new ones each time to improve performance
  • Revoke tokens you no longer need with /Authenticate/RevokeToken/{refreshtoken}
  • If a refresh token is compromised, contact Cloud Factory immediately to prevent audit issues and security risks