> ## Documentation Index > Fetch the complete documentation index at: https://docs.yativo.com/llms.txt > Use this file to discover all available pages before exploring further. # Employee Portal Integration > Employee Portal Integration — integration guide for the Yativo API. The Employee Portal lets an **Employee** (a Corporate Card holder) log in on their own and self-service the things that belong to them: their cards and the memos/invoices on their own card transactions. It is a separate authentication surface from the business/customer API — an employee authenticates as themselves, with a dedicated bearer token, and can only ever see or act on their own data. Employees are created and KYC'd by the owning business (see the Corporate Card Integration guide). An employee can **never** self-register here; they can only log in once the business has created them. All portal endpoints are under `/api/v1/employee`. Authenticated endpoints require the employee bearer token in the `Authorization` header: ``` Authorization: Bearer ``` ## Access & blocking An employee's access is automatically blocked — login is refused and every authenticated call returns `403` — whenever: * the employee's own status is `suspended` or `terminated`; or * the owning customer is banned; or * the owning user account is suspended. When any of these is true the response body carries the reason, e.g. `{ "message": "Owning user account is suspended." }`. The employee's organisation must also be enabled for Business Spend Cards: the owning business must be approved by Yativo, and the employee's customer must hold an approved `faster_payments` endorsement (see the Corporate Card Integration guide). Until both are true, every authenticated call returns `403` with `Your organisation is not enabled for Business Spend Cards.` Login itself still succeeds, so show this message rather than treating it as a login failure. *** ## Authentication (magic link / OTP) Passwordless login: the employee requests a one-time code by email, then exchanges it for a bearer token. ### Request a login code ``` POST /api/v1/employee/auth/magic ``` ```json theme={null} { "email": "jane@company.com" } ``` The employee is emailed a one-time code (no link): 8 letters and digits shown as `XXXX-XXXX` (for example `7KQ2-M9PT`). The response is always the same whether or not the email matches a real employee (so the endpoint can't be used to discover who is an employee): ```json theme={null} { "message": "If that email belongs to an employee, a one-time login code has been sent." } ``` ### Exchange the code for a token ``` POST /api/v1/employee/auth/magic-login ``` ```json theme={null} { "email": "jane@company.com", "token": "7KQ2-M9PT" } ``` Enter the code as shown. Case, spaces and the dash don't matter, and the look-alike letters `O`, `I` and `L` are read as `0`, `1` and `1`. Codes: * expire **10 minutes** after they are issued; * work **once**: requesting a new code replaces the old one; * allow **5 wrong attempts**, after which the code is cancelled and the employee must request a new one (`429` `Too many incorrect attempts. Please request a new login code.`). Requesting codes is limited to 3 per email every 15 minutes (further requests get the same response but send nothing) and 5 per minute per IP. Signing in is limited to 10 attempts per minute per IP. On success: ```json theme={null} { "employee_id": "emp_...", "full_name": "Jane Doe", "email": "jane@company.com", "status": "active", "kyc_status": "approved", "access_token": "", "token_type": "bearer", "expires_in": 3600 } ``` Invalid or expired codes return `The one-time login code is invalid or has expired.` ### Current employee ``` GET /api/v1/employee/me ``` Returns the authenticated employee with their KYC and owning customer. ### Log out ``` POST /api/v1/employee/auth/logout ``` Invalidates the current token. *** ## Card balance ``` GET /api/v1/employee/balance ``` The employee's spendable balance, shared by all of their cards. It is read-only here: the organisation that manages the employee adds and removes funds. ```json theme={null} { "employee_id": "emp_456", "currency": "USD", "has_cardholder": true, "available_balance": 420.50, "ledger_balance": 450.00, "balance_unavailable": false, "accounts": [ { "account_id": "8f0c...", "primary": true, "available_balance": 420.50, "ledger_balance": 450.00, "card_count": 2 } ] } ``` Show `available_balance` as the amount the employee can spend. `ledger_balance` also includes card payments that haven't settled yet. `has_cardholder` is `false` until the employee's first card is issued. If `balance_unavailable` is `true`, the figures may be incomplete; retry shortly. *** ## Cards Full lifecycle management, scoped to the employee's own cards. A card is referenced by its `card_id` (the opaque id returned in card responses). The account that owns the employee's customer can also see and manage every one of these cards, including viewing full card details, through the Corporate Card API (`/api/v1/corporate-card/employees/cards` and `/api/v1/spend/cards/{card_id}/widget-token`). ### List my cards ``` GET /api/v1/employee/cards ``` Optional query: `status`. Returns a paginated list of the employee's cards. ### Get a card ``` GET /api/v1/employee/cards/{card_id} ``` ### View full card details (secure widget) ``` GET /api/v1/employee/cards/{card_id}/widget-token ``` Returns a short-lived link to a secure page that displays the full card number, expiry and CVV: ```json theme={null} { "status": "success", "data": { "iframe": "https://.../api/v1/spend/cards/widget/view/..." } } ``` Embed `data.iframe` as an `