Troubleshooting Environment Access

​

Getting Your Credentials

• Customer ID — your primary account identifier (UUID format)
• API Key — your secret authentication token
• Child ID (if applicable) — issued when your account uses child entities
• Portal URL
• API Base URL

​

Understanding Your Credentials

​

Customer ID (Required)

​

API Key (Required)

​

Child ID (Optional)

• You are accessing the service as part of an organisational division (e.g., regional or country division).
• You are acting as an agent of a service that uses FrankieOne for their KYC/AML needs.

​

Setting Up API Authentication

​

Required Headers

X-Frankie-CustomerID: YOUR_CUSTOMER_ID
api_key: YOUR_API_KEY

​

If You Have a Child Account

X-Frankie-CustomerID: YOUR_CUSTOMER_ID
X-Frankie-CustomerChildID: YOUR_CHILD_ID
api_key: YOUR_API_KEY

​

Header Format Requirements

​

Environment URLs

​

UAT Environment

​

Production Environment

​

Common Authentication Issues

​

Issue 1: Unauthorized (401)

• Incorrect API key or Customer ID
• Missing Child ID when one is required
• Wrong environment (UAT credentials sent to Production, or vice versa)
• Case sensitivity errors in header names

1. Verify header names — check that header names are exactly correct with proper capitalisation: X-Frankie-CustomerID (not X-Frankie-CustomerId), api_key (not API_KEY or api-key).
2. Check for extra spaces — ensure there are no leading or trailing spaces in your credentials.
3. Verify complete credentials — make sure you have copied the entire API key. These are long strings and can be accidentally truncated.
4. Confirm environment match — UAT credentials must be used with the UAT URL, and Production credentials with the Production URL.
5. Check Child ID requirement — if you have a Child ID, you must include the X-Frankie-CustomerChildID header.

​

Issue 2: Bad Request (400)

• Malformed UUID format
• Special characters in credentials
• Incorrect header format

1. Validate UUID format — Customer IDs and Child IDs should be in standard UUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (lowercase hexadecimal characters with hyphens in specific positions).
2. Check for copy-paste issues — when copying from 1Password or email, do not include surrounding quotes, line breaks, or hidden characters.

​

Issue 3: Forbidden (403)

• Attempting to access a child account’s data from a parent account without proper permissions
• Attempting unauthorised operations
• Account permissions not properly configured

​

Issue 4: Not Seeing Entities in Portal

• If your API calls include a Child ID, you need to be viewing the child account in the Portal — not the parent account.
• Parent accounts can view child account data, but child accounts cannot view parent account data or other child accounts’ data.

1. Check the account dropdown in the top-right corner of the Portal.
2. If your API calls use a Child ID, switch to that child account view. If your API calls use only the Customer ID (parent), ensure you are in the parent account view.
3. Verify the entity was created by checking the API response for the entity ID and searching for it in the Portal.

​

Portal Access

​

Requesting Portal Access

• Your name and email address
• The environment you need access to (UAT, Production, or both)
• Whether you need parent or child account access

​

Parent and Child Accounts in the Portal

• Can view all child account data
• Can act as a child account
• Has administrative capabilities and can manage users across all accounts

• Has its own API key
• Cannot see parent account data or other child accounts’ data
• Can have separate billing
• Restricted to its own data view

​

Testing Your Connection

curl --location 'https://api.uat.frankie.one/v2/kyc/ruok' \
  --header 'api_key: YOUR_API_KEY' \
  --header 'X-Frankie-CustomerID: YOUR_CUSTOMER_ID'

{
  "status": "ok"
}

​

Troubleshooting Checklist

1. Are you using the correct environment URL (UAT vs Production)?
2. Are your header names exactly correct (case-sensitive)?
3. Have you copied the complete API key without truncation?
4. Are there any extra spaces in your credentials?
5. If you have a Child ID, are you including it in the X-Frankie-CustomerChildID header?
6. Are your credentials for the correct environment?
7. If using the Portal, are you viewing the correct account (parent vs child)?
8. Have you been granted Portal access for the environment you are trying to access?

​

Understanding API Error Responses

​

Error Response Structure

{
  "requestId": "0123456789ABCDEFGHIJKLMNOP",
  "errorCode": "AUTH-0002",
  "errorMsg": "Unauthorized",
  "details": [
    {
      "issue": "Invalid Authentication provided. Access denied.",
      "issueLocation": "request"
    }
  ]
}

​

Error Code Prefixes

​

Common Authentication Error Codes

​

Getting Help

​

When to Contact FrankieOne Support

• You have not received your credentials.
• You need Portal access.
• You are consistently getting authentication errors after verifying all credentials.
• You need to confirm whether you should have a Child ID.
• You need to verify your account configuration.
• You need parent/child account permissions adjusted.

​

Information to Provide

• The environment you are trying to access (UAT or Production)
• The error message you are receiving (including the error code)
• Whether you are trying to access via API or Portal
• Your Customer ID (safe to share)
• Whether you have a Child ID
• The exact headers you are using (without the actual API key value)
• A sample curl command or API request (with credentials redacted)

​

Best Practices

• Store credentials securely — use environment variables or a secure credential management system.
• Never commit credentials — do not commit API keys to version control.
• Use environment-specific credentials — keep UAT and Production credentials separate.
• Test in UAT first — always test your integration in UAT before moving to Production.
• Verify environment URLs — double-check you are using the correct URL for your environment.
• Keep credentials updated — if credentials are rotated, update them immediately in all systems.

​

Additional Resources

• API Authentication Documentation
• Getting Started Guide
• API Error Codes
• Support Portal