====== API Authentication ======

===== Overview =====

Every Collection API request requires credentials. There are two credential sets — choose the right one for your context.

===== Standard API Credentials =====

Used by external integrations and automated scripts.

^ Parameter ^ Field on Login record ^ Description ^
| ''u'' | ''strLogin_API_UserId'' | API username (not the login email) |
| ''k'' | ''strLogin_API_KeyId'' | API key (long random string) |

These are set by a Level 3 administrator in **Admin → Users → [User] → API Credentials**.

===== In-Browser Credentials (Logged-In User) =====

For JavaScript making API calls on behalf of a logged-in user:

^ Parameter ^ Description ^
| ''id'' | User ID (''intLogin_Id'') |
| ''us'' | API username |
| ''ky'' | API key |

These are passed alongside ''r'', ''g'', and ''f'' as usual.

===== Required Parameters on Every Request =====

^ Param ^ Meaning ^
| ''u'' | API username |
| ''k'' | API key |
| ''r'' | Collection reference (''strCollection_Ref'') — the 15-char alphanumeric ID |
| ''g'' | View (GX group) ID — selects which named filter to use and acts as an auth gate |
| ''f'' | Function name (e.g. ''meta'', ''crosslist'', ''create'') |

===== Optional Parameters =====

^ Param ^ When required ^
| ''p'' | Private key — required when the view has one configured |

===== Auth Failure Codes =====

If authentication fails, the response ''error'' field contains a negative code:

^ Code ^ Meaning ^
| ''-1'' | No username / password passed |
| ''-4'' | Username / password combo not found |
| ''-8'' | View requires a private key — none provided |
| ''-9'' | Private key mismatch |
| ''-10'' | API access disabled for this view |

===== Security Notes =====

  * Credentials are validated against the ''Login'' table via prepared statement — no SQL injection risk
  * API keys should be treated as secrets — do not include them in client-side JavaScript served to users
  * For public-facing endpoints, use a view with a private key and a read-only GX configuration
  * Rate limit: 120 requests per user per minute. Exceeding this returns HTTP 429.

===== Getting the Collection Ref and View ID =====

  * **Collection ref:** visible in the URL when browsing a collection in the admin UI (''?ref=XXXXXXXXXXXXXXX'')
  * **View ID:** call ''f=meta'' first — the response lists all active views and their IDs

===== Quick Start =====

<code>
POST https://yourdomain.com/api/apic.php
u=myapiuser&k=myapikey&r=7mFzPkZUqYJW3QW&g=101&f=meta
</code>

The ''meta'' response gives you everything you need: field names, view IDs, action IDs, and usage templates.