Integration Notes & Best Practices

This guide covers production-ready integration patterns, image guidelines, retry strategies, and security recommendations for Mirrago APIs.

---

Token Expiry & Renewal

Access tokens returned from:

POST /oauth/token

include:

• access_token
• expires_in (seconds)

Tokens are short-lived. Your system should automatically renew them.

Recommended Strategy

1. Store:

   • access_token
   • expires_at = now + expires_in

2. Renew the token 60 seconds before expiry.

3. If any API call returns 401 Unauthorized:

   • Request a new token
   • Retry the original request once
   • If it still fails, surface the error

Example Token Manager (TypeScript)

type TokenResponse = {
  access_token: string;
  expires_in: number;
};

let cachedToken: string | null = null;
let tokenExpiresAt = 0;
const SAFETY_BUFFER = 60_000; // 60 seconds

async function fetchToken(baseUrl: string, clientId: string, clientSecret: string) {
  const res = await fetch(`${baseUrl}/oauth/token`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      client_id: clientId,
      client_secret: clientSecret,
      grant_type: "client_credentials"
    })
  });

  const data = (await res.json()) as TokenResponse;

  cachedToken = data.access_token;
  tokenExpiresAt = Date.now() + data.expires_in * 1000 - SAFETY_BUFFER;

  return cachedToken;
}

export async function getValidToken(baseUrl: string, clientId: string, clientSecret: string) {
  if (cachedToken && Date.now() < tokenExpiresAt) return cachedToken;
  return fetchToken(baseUrl, clientId, clientSecret);
}

---

Handling 401 Errors

If an API call returns:

401 Unauthorized

Your system should:

1. Fetch a new token
2. Retry the failed request once
3. If still failing, log and surface error

This protects against clock drift and revoked tokens.

---

Polling Best Practices

• Poll /v1/getJobStatus/{job_id} every 1 second
• Stop polling after 30 seconds
• Handle failed status gracefully
• Avoid aggressive polling to prevent rate limits

---

Retry Strategy

Scenario	Action
Network timeout	Retry after 2 seconds
500 server error	Retry up to 3 times
401 unauthorized	Renew token and retry once
400 bad request	Do not retry (fix request)

---

Image Guidelines

Model Images

• Front-facing subject
• Neutral background
• Clear lighting
• JPG or PNG format

Garment Images

• Transparent or plain background
• High contrast edges
• PNG or JPG
• Recommended resolution ≥ 1024px

---

Scaling Guidance

• Mirrago APIs are horizontally scalable
• Batch job submission is supported
• Use queues if generating at high volume
• Avoid submitting duplicate identical jobs

---

Security Recommendations

• Never expose client_secret in frontend code
• Store credentials in secure environment variables
• Use HTTPS for all requests
• Rotate credentials periodically

---

Common Mistakes

Issue	Fix
Code blocks rendering as text	Ensure no space after triple backticks
Token expiring mid-request	Renew with 60s safety buffer
Job stuck in processing	Add timeout fallback
Broken images	Ensure URLs are publicly accessible

---