# Avatarak.ir developer documentation > Turn an email address into an avatar and a public profile. Docs: https://avatarak.ir/docs --- # Getting started (https://avatarak.ir/docs/getting-started) Avatarak.ir turns an **email address** into an **avatar** and a **public profile**. A person uploads their photo and details once; every site that knows their email can show them. There are two ways to use it: | | Avatar URL | REST API | |---|---|---| | What you get | the user's photo | profile data: name, bio, website, socials, avatar | | API key | not needed | required (free) | | Call it from | anywhere, even an `` tag | your server | ## Quick start **1. Hash the email.** Every URL is built from the SHA-256 hash of the email address, never the email itself. See [Creating the identifier](/docs/hash). ```js // sha256 of "myemailaddress@example.com" const hash = '84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee'; ``` **2. Show the avatar.** No key, no sign-up: ```html ``` **3. (Optional) Get profile data.** Create an [API key](/docs/authentication) and call the API from your server: ```bash curl -H "Authorization: Bearer YOUR_API_KEY" \ https://avatarak.ir/api/v1/profiles/84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee ``` ## Base URLs | Purpose | URL | |---|---| | Avatar by email hash | `https://avatarak.ir/avatar/{hash}` | | REST API | `https://avatarak.ir/api/v1` | | A public profile | `https://avatarak.ir/{username}` | | Public profile as JSON / Markdown / vCard / embeddable card | `https://avatarak.ir/{username}.json` · `.md` · `.vcf` · `.card` | ## What a user controls People decide what is public. A photo is only served for an email the user has **verified** and marked **public**, and only if they left *show avatar* on. If any of that is not true you receive the default image (avatars) or a `404` (API), and the two cases look exactly the same, so nobody can use your integration to find out which emails have an account. Details: [Privacy and limits](/docs/privacy-and-limits). ## Next steps - [Creating the identifier (hash)](/docs/hash) - [Avatars](/docs/avatars): sizes, defaults, caching - [Authentication](/docs/authentication) and the [API reference](/docs/api-reference) --- # Creating the identifier (hash) (https://avatarak.ir/docs/hash) Every avatar and API URL uses a **consistent hash** of the user's email address. You must produce exactly the same hash the service expects: 1. **Trim** leading and trailing whitespace from the email address. 2. Force all characters to **lower case**. 3. Hash the result with **SHA-256** and write it as 64 lowercase hexadecimal characters. ## A worked example Say a user typed `MyEmailAddress@example.com ` with a trailing space by mistake. Hashing that string directly gives the wrong identifier: ```text sha256("MyEmailAddress@example.com ") = bbb8db824654275128ce09499cbbeff439840ae68f19f83861c243450dc1d6c7 ``` After trimming and lower-casing you get the right one: ```text sha256("myemailaddress@example.com") = 84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee ``` ## Code ```js // Browser or Node 18+ (Web Crypto) async function emailHash(email) { const bytes = new TextEncoder().encode(email.trim().toLowerCase()); const digest = await crypto.subtle.digest('SHA-256', bytes); return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join(''); } ``` ```php str: return hashlib.sha256(email.strip().lower().encode('utf-8')).hexdigest() ``` ```bash email=$(printf '%s' "$EMAIL" | xargs | tr '[:upper:]' '[:lower:]') printf '%s' "$email" | openssl dgst -sha256 | awk '{print $NF}' ``` ## Notes - The hash is a one-way fingerprint, but it is **not secret**: anyone who knows an email can compute it. That is why the service answers identically for unknown, unverified and private emails; see [Privacy and limits](/docs/privacy-and-limits). - Never send the plain email address to the service. You never need to. - Hashing in the browser is fine. Do not use `md5` or `sha1`; only SHA-256 is accepted. - A hash in a URL may be upper or lower case; it is normalised to lower case. Once you have the hash, request an [avatar](/docs/avatars) or a [profile](/docs/api-reference). --- # Avatars (https://avatarak.ir/docs/avatars) ## Request an avatar ```text GET https://avatarak.ir/avatar/{hash} ``` No API key is needed. `{hash}` is the [SHA-256 hash](/docs/hash) of the email address (64 hex characters). ```html Profile photo ``` ## Parameters | Parameter | Default | Description | |---|---|---| | `s` (or `size`) | `80` | Square size in pixels, from `16` to `512`. Values outside the range are clamped. Request about **2×** the displayed size for sharp images on high-density screens. | | `d` (or `default`) | `mp` | What to return when there is no public avatar: `mp` a neutral silhouette (SVG), `identicon` a generated pattern (SVG), `blank` a 1×1 transparent PNG, `404` an empty `404` response. Any other value behaves like `mp`. URLs are **not** accepted. | ## Response - A **square** image, centre-cropped. **JPEG**, or **WebP** when your `Accept` header contains `image/webp`. - Defaults are served as `image/svg+xml` (`mp`, `identicon`), `image/png` (`blank`) or a `404`. ### Identicons `d=identicon` draws a symmetric 5×5 pattern from the hash itself, so every address gets its own recognisable picture. It depends on **nothing but the hash**: an unknown address, an unverified one, a private one and one that simply has no photo all look equally random, so it cannot be used to find out whether an address has an account. | Header | Value | |---|---| | `Cache-Control` | `public, max-age=3600` for photos, `public, max-age=300` for defaults | | `ETag` | present; send `If-None-Match` to receive `304 Not Modified` | | `Vary` | `Accept` | | `Access-Control-Allow-Origin` | `*` (usable from any page, including ``) | | `Cross-Origin-Resource-Policy` | `cross-origin` | The photo URL does not change when the user uploads a new photo, so the browser or CDN picks it up when the cache expires (at most one hour for photos). ## When is a photo returned? Only when **all** of these hold: the email is **verified** by its owner, marked **public**, the user's *show avatar* switch is on, and a photo is set. Otherwise you get the default image, identical for unknown, unverified and private emails. This is deliberate; see [Privacy and limits](/docs/privacy-and-limits). ## A profile's own avatar Public profile pages use a URL based on the username instead of an email: ```text GET https://avatarak.ir/{username}/avatar ``` It accepts the same `s` and `d` parameters and returns the photo whenever the profile is public and *show avatar* is on. No email is involved, so verification is not required. When there is no photo, this URL returns the person's **initials** on a colour chosen from their username (`d=initials`, the default here); `d=mp`, `identicon`, `blank` and `404` work too. The initials are available only on this URL, never on `/avatar/{hash}`, because showing a name for a hash would reveal that the address has an account. ## Examples ```js const url = `https://avatarak.ir/avatar/${hash}?s=96&d=404`; const res = await fetch(url); const hasAvatar = res.ok; // 404 means "no public avatar": show your own placeholder ``` ```php '; ``` ```css .user-avatar { background: url('https://avatarak.ir/avatar/HASH?s=128') center / cover; border-radius: 50%; } ``` ## Limits Avatar requests are limited to **600 per minute per IP address**. Browsers and CDNs cache responses, so normal pages stay far below that; put a CDN in front if you serve many users from one address. See [Privacy and limits](/docs/privacy-and-limits). --- # Authentication (https://avatarak.ir/docs/authentication) The [avatar URL](/docs/avatars) is public. The **REST API** needs an **API key**. Keys are free and belong to one *site* (an app or website you connect). ## Create a key 1. Sign in to your dashboard and open **Developers**. 2. Enter a **site name** and its **domain**, then press **Create key**. 3. **Copy the key immediately.** It is shown only once; only a hash is stored, so it cannot be recovered. How many sites you can have depends on your [plan](/docs/plans) (3 on Free). Keys look like `avk_` followed by 40 random characters. ## Send the key Use a bearer token in the `Authorization` header (or the `X-API-Key` header): ```bash curl -H "Authorization: Bearer avk_YOUR_API_KEY" \ https://avatarak.ir/api/v1/profiles/84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee ``` ```js // Node 18+, on your SERVER const res = await fetch('https://avatarak.ir/api/v1/profiles/' + hash, { headers: { Authorization: `Bearer ${process.env.AVATARAK_API_KEY}` }, }); const { data } = await res.json(); ``` ```php true, CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AVATARAK_API_KEY')], ]); $profile = json_decode(curl_exec($ch), true)['data'] ?? null; ``` ## Key scopes When you create a key you choose what it may do: `profiles:read` (one profile by hash) and `profiles:lookup` (up to 100 at once). A request outside a key's scopes gets `403`. Keys made before scopes existed keep full access. You can try every endpoint in your browser at [/docs/api-explorer](/docs/api-explorer); the machine-readable description is at [/docs/openapi.json](/docs/openapi.json). ## Base URL ```text https://avatarak.ir/api/v1 ``` All responses are JSON. Errors have the shape `{"message": "..."}`; see the [API reference](/docs/api-reference#errors). ## Rate limit Each key is limited per minute (default **600 requests**). Every response carries: | Header | Meaning | |---|---| | `X-RateLimit-Limit` | requests allowed per minute for this key | | `X-RateLimit-Remaining` | requests left in the current minute | | `Retry-After` | (only on `429`) seconds to wait | ## Keep your key safe - **Never put the key in client-side code** (a web page, a mobile app). Call the API from your server and pass the result to the browser. - Store it in an environment variable or a secrets manager, not in your repository. - Always use HTTPS. - If a key leaks, delete the site in your dashboard and create a new key; the old one stops working immediately. --- # API reference (https://avatarak.ir/docs/api-reference) Base URL: `https://avatarak.ir/api/v1`. Every request needs an [API key](/docs/authentication). Responses are JSON. ## Get a profile ```text GET /api/v1/profiles/{hash} ``` `{hash}` is the [SHA-256 hash](/docs/hash) of the email (64 hex characters). ```bash curl -H "Authorization: Bearer avk_YOUR_API_KEY" \ https://avatarak.ir/api/v1/profiles/f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7 ``` ```json { "data": { "hash": "f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7", "username": "javid", "profile_url": "https://avatarak.ir/javid", "name_fa": "جاوید میرزایی", "name_en": "Javid Mirzaei", "headline": "Founder at Example", "location": "Tehran, Iran", "bio": "Full-stack engineer and founder.", "website": "https://javid.example.ir", "socials": { "github": "javid", "telegram": "javid_t" }, "links": [{ "label": "Blog", "url": "https://javid.example.ir/blog" }], "verified_accounts": [{ "network": "website", "identifier": "javid.example.ir", "url": "https://javid.example.ir" }], "avatar_url": "https://avatarak.ir/avatar/f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7" } } ``` The response has `Cache-Control: private, max-age=60`. ## Look up many profiles ```text POST /api/v1/profiles/lookup ``` Send between 1 and **100** hashes in one request (duplicates are merged, upper-case is accepted). The result is an object keyed by hash; hashes without a public profile are `null`. ```bash curl -X POST -H "Authorization: Bearer avk_YOUR_API_KEY" -H "Content-Type: application/json" \ -d '{"hashes":["f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7","84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee"]}' \ https://avatarak.ir/api/v1/profiles/lookup ``` ```json { "data": { "f7254a5b7d62b61c5353da4a235812f4b2171e8f16fd876a210d268da1793fd7": { "username": "javid", "...": "same fields as above" }, "84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee": null } } ``` Use this to render a list of comments or members with one call instead of many. ## Profile object | Field | Type | Description | |---|---|---| | `hash` | string | the identifier you asked for (lower case) | | `username` | string | the profile's username | | `profile_url` | string | the public profile page | | `name_fa` | string \| null | Persian display name | | `name_en` | string \| null | English display name | | `headline` | string \| null | short title, e.g. job or tagline | | `location` | string \| null | free-text location | | `bio` | string \| null | short biography | | `website` | string \| null | personal website | | `socials` | object | network → handle, e.g. `{"github": "javid"}`; `{}` when empty | | `links` | array | `[{label, url, description?, image?}]`; `[]` when empty | | `verified_accounts` | array | `[{network, identifier, url}]`, only accounts the user proved they own; `url` is `null` for LinkedIn; `[]` when none | | `avatar_url` | string \| null | the [avatar URL](/docs/avatars), or `null` when the user hides the photo | `socials` holds handles here; the public [JSON export](/docs/exports) returns full URLs instead and adds `display_name`, `verified`, `created_at` and `updated_at`. ## Errors | Status | Body | When | |---|---|---| | `401` | `{"message": "Invalid or missing API key."}` | no key, wrong key, or a deleted site. Sends `WWW-Authenticate: Bearer`. | | `404` | `{"message": "Profile not found."}` | the profile does not exist **or is not public**. See below. | | `422` | `{"message": "...", "errors": {"hashes": ["..."]}}` | `lookup` with an empty list, more than 100 hashes, or a value that is not 64 hex characters | | `429` | `{"message": "Rate limit exceeded."}` | too many requests. Wait `Retry-After` seconds. | ### Why one `404` for everything Unknown email, unverified email, private email and hidden profile all return the **same** `404` (and `lookup` returns `null`). This is intentional: it stops anyone from using the API to discover which email addresses have an account. Do not try to tell the cases apart. See [Privacy and limits](/docs/privacy-and-limits). --- # Webhooks (https://avatarak.ir/docs/webhooks) Instead of polling the [API](/docs/api-reference), add a **webhook** and we call your server when something changes. Webhooks come with the **Pro** plan and above (see [Plans](/docs/plans)). Add one in the panel under **Developers → Webhooks**. ## Events | Event | When | |---|---| | `profile.updated` | A profile field changed. `data.changed` lists which fields. | | `avatar.changed` | An avatar was uploaded or deleted. | | `verification.added` | A verified account was added (`data.network`, `data.identifier`). | | `verification.removed` | A verified account was removed. | | `ping` | The test you send from the panel. | ## The request We `POST` JSON to your address. It must be a public **https** URL: private, loopback and link-local addresses are refused, redirects are not followed, and credentials in the URL are not allowed. ```json { "id": "5b1e0b0e-6a4c-4e5e-9c53-1d3f4b8c8d11", "type": "profile.updated", "created_at": "2026-11-18T12:00:00+00:00", "data": { "changed": ["headline"], "username": "javid", "profile_url": "https://avatarak.ir/javid", "email_hashes": ["9d86ec2b…"] } } ``` `email_hashes` are the SHA-256 hashes of **your own** verified addresses, so you can match the event to a user on your side. The payload never contains an email address. Headers: `Avatarak-Event`, `Avatarak-Delivery` (the event `id`, use it to ignore duplicates) and `Avatarak-Signature`. ## Verify the signature Each webhook has a secret (`whsec_…`) shown **once** when you create it. The signature header is `t=,v1=`, where `v1` is `HMAC-SHA256(secret, ".")`. Check it against the **raw** request body, and reject old timestamps (5 minutes is a good limit). ```php use Avatarak\Webhook; $ok = Webhook::verify(file_get_contents('php://input'), $_SERVER['HTTP_AVATARAK_SIGNATURE'] ?? null, $secret); ``` ```js import { verifyWebhook } from '@avatarak/client'; const ok = await verifyWebhook(rawBody, req.headers['avatarak-signature'], secret); ``` ## Retries Answer with any `2xx` within 8 seconds. Otherwise we retry up to 5 times, with growing pauses (30 s, 2 min, 10 min, 1 h). After **20 failures in a row** the webhook is switched off automatically; turn it back on in the panel. Make your handler idempotent: the same event can arrive more than once. --- # Libraries (PHP and JavaScript) (https://avatarak.ir/docs/sdks) You can call the [REST API](/docs/api-reference) with any HTTP client, but the official libraries hash the address for you, batch lookups, and turn errors into typed exceptions. Both live in this repository under `packages/`. | Library | Install | Use it for | |---|---|---| | **PHP** `avatarak/avatarak-php` | `composer require avatarak/avatarak-php` | any PHP 8.1+ app, with Laravel integration built in | | **JavaScript** `@avatarak/client` | `npm install @avatarak/client` | browsers, Node 18+, Deno, Bun. No dependencies | > Keep your API key on the **server**. Profile lookups need it, so call them from PHP or Node, not from a public web page. Avatar URLs need **no key** and are safe in the browser. ## PHP ```php use Avatarak\Client; $avatarak = new Client('avk_YOUR_API_KEY', 'https://avatarak.ir'); // No key, no request: just a URL $avatarak->avatarUrl('ali@example.com', size: 96, default: 'identicon'); // One profile, or null when there is no public profile $profile = $avatarak->profile('ali@example.com'); echo $profile?->displayName(); // Many at once: any number of addresses, sent in batches of 100 $profiles = $avatarak->lookup($users->pluck('email')); // [hash => ?Profile] ``` `Profile` has typed properties for every field of the [API response](/docs/api-reference) (`nameFa`, `headline`, `links`, `verifiedAccounts`, `avatarUrl`…) and `isVerified('github')`. Errors are exceptions: `AuthenticationException` (401), `RateLimitException` (429, with `retryAfter` seconds) and the base `ApiException`. ### Laravel The package is auto-discovered. Add to `.env`: ```text AVATARAK_KEY=avk_YOUR_API_KEY AVATARAK_URL=https://avatarak.ir ``` ```php use Avatarak\Laravel\Facades\Avatarak; Avatarak::profile($user->email); ``` ```blade ``` The component renders an `` with a 2× `srcset` and never writes the address into the page. ## JavaScript ```js import { Avatarak, avatarUrl } from '@avatarak/client'; // Browser or server, no key: const url = await avatarUrl('ali@example.com', { size: 96, default: 'identicon' }); // Server only, with the key: const api = new Avatarak({ apiKey: process.env.AVATARAK_KEY, baseUrl: 'https://avatarak.ir' }); const profile = await api.profile('ali@example.com'); // object or null const many = await api.lookup(['a@x.ir', 'b@y.com']); // { hash: object | null } ``` Errors: `AuthenticationError`, `RateLimitError` (`retryAfter`) and `ApiError`. TypeScript types are included. ### Web component For plain HTML pages, no build step: ```html ``` The address is hashed in the browser and never sent. Attributes: `email` or `hash`, `size` (16–512), `default`, `alt`, and `base-url` for your own install. ## Self-hosting Pass your own server as the base URL (`new Client($key, 'https://id.example.com')`, `baseUrl` in JS, or `AVATARAK_URL` in Laravel). Everything else is identical. --- # Public profile data (https://avatarak.ir/docs/exports) Every **public** profile page has machine-readable versions, built from the same data the page shows. They need **no API key** and are meant for other sites to use. Emails are never included. | Format | URL | Content type | |---|---|---| | JSON | `https://avatarak.ir/{username}.json` | `application/json` | | Markdown | `https://avatarak.ir/{username}.md` | `text/markdown` | | vCard 3.0 | `https://avatarak.ir/{username}.vcf` | `text/vcard` (downloads as `{username}.vcf`) | | Embeddable card | `https://avatarak.ir/{username}.card` | `text/html` | | QR code | `https://avatarak.ir/{username}.qr` | `image/svg+xml` | | Share image | `https://avatarak.ir/{username}/share.svg` | `image/svg+xml` (1080×1350) | | Printable card | `https://avatarak.ir/{username}/print` | `text/html` | If the profile does not exist or the user switched the page off, every format returns `404`. ## JSON ```bash curl https://avatarak.ir/javid.json ``` ```json { "username": "javid", "url": "https://avatarak.ir/javid", "display_name": "جاوید میرزایی", "name_fa": "جاوید میرزایی", "name_en": "Javid Mirzaei", "headline": "Full-stack engineer", "location": "Tehran", "bio": "Founder and engineer.", "website": "https://javid.example.ir", "avatar_url": "https://avatarak.ir/javid/avatar?s=512&v=Kx3Qm1", "verified": true, "socials": { "github": "https://github.com/javid" }, "links": [ { "label": "Portfolio", "url": "https://javid.example.ir/work", "description": "My projects.", "image": "https://avatarak.ir/thumb/9c1f..." } ], "verified_accounts": [ { "network": "website", "identifier": "javid.example.ir", "url": "https://javid.example.ir" }, { "network": "telegram", "identifier": "javid_t", "url": "https://t.me/javid_t" } ], "gallery": [ { "url": "https://avatarak.ir/javid/gallery/7/full", "thumb_url": "https://avatarak.ir/javid/gallery/7/thumb", "caption": "Our office", "width": 1600, "height": 1067 } ], "sections": [ { "title": "Opening hours", "body": "Sat–Wed, 9 to 17" } ], "created_at": "2026-11-01T10:12:00+00:00", "updated_at": "2026-11-17T20:41:00+00:00" } ``` | Field | Notes | |---|---| | `avatar_url` | `null` when the user hides their photo | | `verified` | `true` if the owner verified at least one email | | `socials` | network → **full URL** (unlike the REST API, which returns handles) | | `links[].image` | present only when the user shows link images | | `verified_accounts` | accounts the user *proved* they own: see [Verified accounts](/docs/verified-accounts) | | `gallery` | the photos the owner added, in order; empty when hidden. Full size is at most 1600 px | | `sections` | free-text sections the owner wrote (`title`, `body`; plain text) | | `language` | `fa` or `en`: the language of the texts in this response | | `languages` | the languages the page is available in; a bilingual profile also has `translations` | ## Languages A profile can speak **Persian only**, **English only** or **both** (set in the panel under *Design → Language of your public page*). - **Single language:** the whole page, labels and text direction included, is always in that language, whatever language the visitor uses. Texts never mix. - **Bilingual:** every text exists in two versions. A visitor sees the one that matches their language (`?lang=fa` or `?lang=en` picks it explicitly), the page shows a language switch, and `hreflang` links are added for search engines. If one version is empty the other is shown. `language` tells you which language the texts in the response are in, and `languages` lists what the page offers. On a bilingual profile `/{username}.json` also carries a `translations` object with both versions, and `.json`, `.md` and `.vcf` accept `?lang=`. The REST API accepts `?lang=` too. Fields the user left empty are `null`, an empty object or an empty list. ## Use it from a browser These endpoints send `Access-Control-Allow-Origin: *`, so you can read them from any web page: ```js const profile = await (await fetch('https://avatarak.ir/javid.json')).json(); document.querySelector('#name').textContent = profile.display_name; ``` ## Embeddable card A small profile card you can place on your own page: ```html ``` The same code is available in the **Advanced details** window of any profile page, together with a downloadable **QR code** of the profile URL (made in the browser). ## QR code, business card and share image `/{username}.qr` is a vector QR code of the profile address, so it stays sharp at any print size. | Parameter | Default | Description | |---|---|---| | `size` | `512` | width and height in pixels, `64`–`2048` | | `fg`, `bg` | `101517`, `ffffff` | colours as hex (`1D4FC4` or `#abc`). A pair with a contrast below 3:1 is refused with `422`, because a phone could not scan it. | | `margin` | `2` | quiet-zone width in modules, `0`–`8` | | `content` | the address | `vcard` encodes the contact card instead (falls back to the address if it would be too dense to scan reliably) | | `download` | | `1` sends it as a file attachment | `/{username}/share.svg` is a portrait card (photo or initials, name, headline, QR code) for a post or story; add `?download=1` to save it. `/{username}/print` is a print-ready **85×55 mm business card**; add `?sheet=1` for an A4 sheet of ten. ## Headers and limits | Header | Value | |---|---| | `Cache-Control` | `public, max-age=300` | | `Access-Control-Allow-Origin` | `*` | | `X-Robots-Tag` | `noindex, nofollow`, unless the user allowed search-engine indexing | Limit: **60 requests per minute per IP address**. Cache the result on your side instead of requesting on every page view. --- # Verified accounts (https://avatarak.ir/docs/verified-accounts) A **verified account** is one the user has *proved* they own. It appears on their profile with a blue check and is listed in the `verified_accounts` field of the [public JSON](/docs/exports). Four kinds exist today: **websites**, **GitHub**, **LinkedIn** and **Telegram**. The `network` field of each entry is `website`, `github`, `linkedin` or `telegram`. Verification is also what makes a link trustworthy: verified accounts are rendered with `rel="me"`, the standard way to say "this link is the same person". ## Website The user enters a domain in the dashboard and publishes the code we give them in **any one** of three ways, then presses *Check now*: | Method | What to publish | |---|---| | Meta tag | `` in the `` of the home page | | File | `https://DOMAIN/.well-known/avatarak-verification.txt` containing only `TOKEN` | | DNS | a `TXT` record on `DOMAIN` with the value `avatarak-verification=TOKEN` | We fetch the page from our server. If the site redirects to a **different domain**, nothing is proved (an apex-to-`www` redirect is fine). Only public addresses on ports 80 and 443 are contacted. ## GitHub Two ways, both stored by the **numeric GitHub id** (a login can be renamed and taken by someone else, an id cannot): | Method | How | |---|---| | Public gist | the user creates a **public** gist named `avatarak-verification.txt` containing `avatarak-verification=TOKEN` and presses *Check now*. Works with no server setup. | | Sign in with GitHub | one click, available when the server has an OAuth app configured. We only read the public login and id. | Secret gists and gists from other accounts are ignored. The gist can be deleted once the account is verified. ## LinkedIn Only when the server has a LinkedIn app configured (*Sign In with LinkedIn using OpenID Connect*). The user signs in with LinkedIn; we keep LinkedIn's stable id and the **name** on the account. LinkedIn does not give a public profile address, so a verified LinkedIn entry has **`url: null`** in the API and JSON: show the name, not a link. ## Telegram The user types their Telegram username, presses **Verify with Telegram**, opens our bot and presses **Start**. Telegram tells us who pressed it, and we confirm the username matches the one entered. The account is stored by its **numeric Telegram id**, because a username can be released and registered by someone else later. ## Rules - One external account can be verified for **one** user. A second claim is refused. - A code is single-use, expires after **72 hours** and allows at most 40 checks. - Ownership is checked **once**, when verifying. A domain that expires later stays verified until the user removes it. - We store only the account identifier, the method and the time. No tokens from other services. ## Optional GitHub settings (self-hosting) The gist method needs nothing. Two optional additions in `.env`: ```text GITHUB_API_TOKEN= # raises GitHub's anonymous rate limit (60 requests/hour per server IP) GITHUB_CLIENT_ID= # an OAuth app enables "Sign in with GitHub" GITHUB_CLIENT_SECRET= ``` Set the OAuth app's callback URL to `https://avatarak.ir/account/verifications/github/callback`. ## Running the Telegram bot (self-hosting) 1. Create a bot with [@BotFather](https://t.me/BotFather) and note its token and username. 2. Add to `.env` (make the secret with `openssl rand -hex 32`): ```text TELEGRAM_BOT_TOKEN=123456:ABC... TELEGRAM_BOT_USERNAME=your_bot TELEGRAM_WEBHOOK_SECRET=<64 random hex characters> ``` 3. Receive messages in **one** of two ways: ```bash php artisan telegram:webhook # production: an HTTPS URL Telegram can reach php artisan telegram:poll # local development: no public URL needed ``` The webhook rejects any request without the exact secret in `X-Telegram-Bot-Api-Secret-Token`, and does not exist at all until Telegram is configured. Never share the bot token; if it leaks, send `/revoke` to BotFather. > Telegram is filtered in some countries. The server must be able to reach `api.telegram.org`, and Telegram must be able to reach your webhook URL. If `telegram:poll` fails with a connection error, try `--timeout=3` or run it through a VPN or proxy. --- # Plans and limits (https://avatarak.ir/docs/plans) Everything essential is **free**: your photo, your public profile, verified accounts, the QR code, statistics and the API for small sites. Paid plans raise the limits and add features for people who run more. | | Free | Pro | Business | |---|---|---|---| | Connected sites (API keys) | 3 | 25 | 200 | | API requests per minute, per key | 600 | 6,000 | 60,000 | | Gallery photos | 3 | 12 | 30 | | Custom sections | 2 | 6 | 12 | | Webhooks | – | 3 | 20 | | Custom domain for the profile | – | ✓ | ✓ | | White-label (no Avatarak.ir link on the profile) | – | – | ✓ | The live numbers (and prices) are in the public file [`/pricing.json`](https://avatarak.ir/pricing.json), which is what this site's pricing section reads. ## Paying Open **Plan & billing** in the dashboard, choose a plan and *Monthly* or *Yearly*, and you are sent to the payment page of the gateway. When you come back, we ask the gateway to **confirm** the payment before activating anything; the amount is always the one on our side, never one sent by the browser. Each payment buys exactly one period, and a receipt is emailed. - Buying the **same plan again** adds time after the current period ends. - Buying a **higher plan** starts immediately; while two plans are active the higher one applies. There is no proration. - Plans do **not** renew by themselves. We email you 7 days before one ends. ## When a plan ends You go back to Free. **Nothing is deleted.** Things above the Free limits keep working until you change them, but you cannot add more: for example, if you have 10 sites you keep them, and you can add one only after you are back under 3. ## Per-key limits A key's rate limit comes from its owner's plan. In rare cases (support, abuse) an administrator can set an explicit limit on one key; that overrides the plan, up or down, until it is cleared. ## Custom domains Pro and Business can show their profile on their own domain (**Custom domain** in the dashboard). The customer adds a **TXT** record to prove they own it and a **CNAME** to `CUSTOM_DOMAIN_TARGET` (or an A record to the same server). On that domain the visitor sees **only** the profile (`/`), its photo (`/avatar`) and its exports (`/profile.json`, `.md`, `.vcf`, `.card`, `.qr`); every other path, including the dashboard, sign-in and the API, answers `404`. If the plan ends, the profile is hidden or the owner is suspended, the domain stops at once. ## Self-hosting Billing is **off** unless you turn it on. Set `BILLING_GATEWAY=zarinpal` with your `ZARINPAL_MERCHANT_ID` (add `ZARINPAL_SANDBOX=true` to test), and change the numbers in `config/plans.php` or the `PLAN_*_PRICE_*` variables. `BILLING_GATEWAY=fake` pretends every payment succeeds so you can try the flow on your computer; it refuses to run in production. With billing off, administrators can still give any plan for any number of days from the admin area. --- # Privacy and limits (https://avatarak.ir/docs/privacy-and-limits) ## What we never expose - **Email addresses.** Not on the public page, not in the API, not in any export. Only a one-way hash appears in URLs. - Anything the user switched off: the photo, the profile page, or search-engine indexing. Each is a separate switch in the dashboard. - Your API key, which is stored only as a hash. ## Identical answers For an email that is unknown, unverified or private, the service answers **exactly the same way**: the default image for avatars and a plain `404` (or `null` in `lookup`) for the API. Because a hash is not secret (anyone can compute the hash of an address they know), different answers would reveal which people have an account. Build your integration so it never needs to tell these cases apart. A user can also hide their whole profile page; then the page, its avatar and its JSON/Markdown/vCard/card exports all return `404`. ## Limits | What | Limit | |---|---| | Avatar URLs (`/avatar/{hash}`, `/{username}/avatar`) | 600 requests per minute per IP | | REST API | 600 requests per minute per API key (configurable per site) | | `profiles/lookup` | 100 hashes per request | | Public exports (`.json`, `.md`, `.vcf`, `.card`) | 60 requests per minute per IP | | Avatar size (`s`) | 16 to 512 pixels | | Sites per user | 10 | When you exceed a limit you get `429` with `Retry-After`. ## Caching Cache politely and your integration stays fast and well inside the limits: | Data | Suggested cache | |---|---| | Avatar image | let the browser/CDN follow `Cache-Control` (1 hour) and use `ETag` | | API profile | up to 1 hour | | Public JSON | up to 5 minutes (`Cache-Control: public, max-age=300`) | If a profile later returns `404`, the user hid it or removed it: stop showing the data you stored. ## Statistics Each user can see how often their avatar, profile, exports and API data were used, and on which sites. We store **daily counters only**: how many times, and the **host** of the referring site (for example `blog.example.com`). We do **not** store IP addresses, browsers, cookies or anything about the visitor, and the owner's own visits, bots and `HEAD` requests are not counted. Rows older than 90 days are deleted. Only the data of a **real photo or profile** is counted, never the generic default image, so statistics cannot be used to find out whether an address has an account. ## Your account data Each user can **download everything we hold about them** (a ZIP with their profile, emails, verified accounts, sites without API keys, statistics and photos) and **delete their account** from *Security* in the dashboard. Deleting removes the account, profile, photos, emails, keys and statistics at once; copies in backups disappear when the backup rotates out (about 14 days). Two-step sign-in (an authenticator app, with recovery codes) and a list of active sessions are in the same place, and we email users about a **new device**, a **password** or **two-step change** and a **suspension**. The full legal texts are the [Terms](/terms) and the [Privacy Policy](/privacy). ## Responsible use - **Do not enumerate or guess** hashes, or test lists of emails to find who has an account. - Use a profile's data only to show it to *that person's own audience* in the context they chose, and respect their later changes by refreshing regularly. - Respect `X-Robots-Tag: noindex`. - Do not call the API from client-side code with your key; proxy through your server. - Do not resell or republish the data as a bulk dataset. We may rate-limit or disable keys that break these rules. To report abuse, open an issue in the project's GitHub repository; for a security vulnerability, use the repository's Security tab (private reporting) instead of a public issue. --- # Deployment (https://avatarak.ir/docs/deployment) The repository ships a production stack: **nginx**, **PHP-FPM**, a **queue worker**, a **scheduler**, **MySQL** and **Redis**, wired together with Docker Compose. You need a Linux server with Docker, a domain name, and an SMTP account for email. > This guide matches the files in the repository (`Dockerfile`, `docker-compose.yml`, `docker/`, `.env.production.example`). Read them once; they are short. ## 1. First start ```bash git clone https://github.com/avatarak/avatarak.git && cd avatarak cp .env.production.example .env ``` Edit `.env`. Everything marked `!!!` must be changed: the public address (`APP_URL`), the database passwords, and the SMTP settings. Make the application key: ```bash docker compose run --rm app php artisan key:generate --show # paste the result into APP_KEY docker compose up -d --build docker compose exec app php artisan admin:create you@example.com ``` The app container runs the migrations and caches its configuration on every start. The stack listens on port `8080` (`WEB_PORT` in `.env`). ## 2. HTTPS Put something that terminates TLS in front of port `8080`. The simplest is [Caddy](https://caddyserver.com), which gets certificates by itself: ```text avatarak.ir { reverse_proxy 127.0.0.1:8080 } ``` Nginx with certbot, Traefik, a cloud load balancer or Cloudflare work equally well. Keep `TRUSTED_PROXIES=*` in `.env` while the app is reachable **only** through that proxy; this is what makes links, QR codes and cookies use `https` and records the real visitor address. If port `8080` is also open to the internet, list the proxy's addresses instead (`TRUSTED_PROXIES=10.0.0.0/8`) or close the port. ## 3. Email Sign-in codes and verification messages are real email, sent through the queue worker. Fill in `MAIL_*` in `.env`, then check it: ```bash docker compose exec app php artisan mail:test you@example.com ``` The command sends one message immediately and tells you what went wrong. Use a sending domain with SPF and DKIM set up, or messages will land in spam. Watch the worker with `docker compose logs -f queue`. ## 4. Telegram and GitHub (optional) Fill in the `TELEGRAM_*` and `GITHUB_*` lines of `.env`, then `docker compose up -d`. In production use the webhook, not polling: ```bash docker compose exec app php artisan telegram:webhook ``` See [Verified accounts](/docs/verified-accounts) for the details. ## 5. CDN Avatars are the busiest URL and are built to be cached: they carry no cookies, an `ETag`, `Cache-Control` and open CORS. There are three layers: - The **browser** keeps a photo for `AVATAR_MAX_AGE` seconds (default one hour). - The bundled **nginx** keeps a copy for 60 seconds, so a burst of identical requests reaches PHP once. - A **CDN** (Cloudflare, ArvanCloud, Bunny…) in front of the domain does the heavy lifting. Set `AVATAR_S_MAXAGE` (seconds, `600` in the example) to give shared caches their own lifetime through `s-maxage`. A changed photo keeps its URL, so a CDN may keep showing the old one for up to `AVATAR_S_MAXAGE` seconds. That is why it is **minutes, not days**; purge a URL by hand if you must. Generated placeholder images never get `s-maxage`. Two practical notes. The format depends on the `Accept` header (WebP or JPEG, `Vary: Accept`), so use a CDN setting that respects `Vary`, or cache JPEG only. And do not cache `/admin`, `/account` or `/login`: they are dynamic and private. ## Custom domains and HTTPS Customers' domains need a certificate each. With Caddy this is automatic (*on-demand TLS*): Caddy asks the app, before it gets a certificate, whether it really serves that domain. ```text { on_demand_tls { ask http://127.0.0.1:8080/_internal/domain-check?key=YOUR_DOMAIN_CHECK_KEY } } avatarak.ir { reverse_proxy 127.0.0.1:8080 } https:// { tls { on_demand } reverse_proxy 127.0.0.1:8080 } ``` Set `DOMAIN_CHECK_KEY` (a long random string) and `CUSTOM_DOMAIN_TARGET` (for example `domains.avatarak.ir`, a DNS name pointing at your server) in `.env`. Without a key the check endpoint is off and no certificates are issued. It approves only verified domains whose owner still has a plan with custom domains and is not suspended. ## 6. Backups ```bash docker compose exec app php artisan backup:run ``` writes `storage/app/backups/avatarak-YYYY-MM-DD_HHMMSS.zip`: a database dump plus every uploaded photo and thumbnail, and keeps the newest `BACKUP_KEEP` (14). The scheduler runs it every night at 02:30. Set `BACKUP_DISK` to an S3-compatible disk to keep copies **off the server**; a backup on the same machine does not survive losing it. To restore into a fresh install: unzip the file, load `database.sql` (`mysql avatarak < database.sql`) and copy the `files/` folder into `storage/app/`. Try a restore once before you need it. ## 7. Updates ```bash git pull docker compose up -d --build ``` Migrations run automatically; the queue worker and scheduler restart with the new code. Take a `backup:run` first. ## Monitoring `/up` answers `200` while the process is alive. `/up/ready` also checks the **database, cache and file storage** and answers `503` with only the names of what failed. Point your uptime monitor at `/up/ready`. The admin [dashboard](/docs/administration) shows warnings for settings that are wrong on a live server. ## Checklist before launch - `LEGAL_ENTITY` and `LEGAL_CONTACT_EMAIL` are set and a lawyer has read `/terms` and `/privacy` (the texts are in `resources/legal/`). - `ADMIN_REQUIRE_2FA=true`, and every administrator has turned on two-step sign-in. - `APP_DEBUG=false`, a real `APP_URL` with `https`, a unique `APP_KEY` (keep a copy: losing it invalidates sessions). - `mail:test` succeeds and a sign-up email arrives in a real inbox. - `backup:run` works, and a copy lives somewhere other than the server. - The queue worker and the scheduler containers are running (`docker compose ps`). - Only ports 80 and 443 are open to the internet. --- # Administration (https://avatarak.ir/docs/administration) Every install has an **admin area** at `/admin`. It is for the people who run the service: reviewing reports, suspending abusive accounts, managing API keys and watching how the service is used. Normal users cannot see it; for them `/admin/api` simply answers `404`. ## Creating the first administrator ```bash php artisan admin:create you@example.com --name="Your Name" ``` A password is generated and printed once (add `--password=` to choose your own). You can also sign in with an email code. Later: ```bash php artisan admin:grant someone@example.com # make an existing user an administrator php artisan admin:grant someone@example.com --revoke # take it away (never the last administrator) ``` Then open `/admin` (or **Admin** in the account menu). ## What you can do | Area | Purpose | |---|---| | **Dashboard** | Users, public profiles, photos, requests, verified accounts, sites and open reports; 30-day growth and traffic charts; the sites using the service most; and a system check that warns about settings that are wrong on a live server (debug on, mail only logged, `sync` queue…). | | **Users** | Search by name, email, username or id; filter administrators, suspended users, unverified emails, owners of sites. A side panel shows everything about a user and offers the actions below. | | **Reports** | Visitors can report a profile (spam, impersonation, inappropriate content, illegal content, other). Review each, mark it *actioned* or *dismissed* with a note, close every open report on the same profile at once, or reopen one. | | **Sites & keys** | Every connected site: owner, last use, rate limit. Disable a key, change its limit, or delete the site. | | **Verified accounts** | Search every verified website, GitHub and Telegram account, and revoke a verification. | | **Audit log** | Every administrator action, newest first. | ### Actions on a user - **Suspend**: needs a reason. The user is signed out on their next request, their profile, exports and avatar disappear everywhere (the [API](/docs/api-reference) included) and their API keys stop working. Lifting the suspension restores everything. - **Change username**, **remove photo** (or the whole photo library), **clear profile content** (bio, headline, location, website, links, socials, names), **make or remove administrator**. - **Delete**: removes the account, profile, photos, emails, keys, statistics and reports for good. You must type the user's email to confirm. You can never suspend or delete yourself or another administrator, and nobody can remove their own administrator access. Remove another administrator's access first, then act on the account. ## Settings, announcements and exports Open **Settings & notices** in the admin panel. - **Switches**: new sign-ups (`REGISTRATION_OPEN`), view statistics (`STATS_ENABLED`), webhooks (`WEBHOOKS_ENABLED`) and the payment gateway (`BILLING_GATEWAY`). A switch changed here wins over `.env` without a redeploy; **Reset** hands control back to `.env`. Secrets such as the ZarinPal merchant id stay in `.env` only. - **Announcements**: a notice shown at the top of the sign-in page and of every user's panel, in Persian and (optionally) English, with a type (info, good news, warning), an optional start and end time, and whether users may close it. - **CSV exports**: users, reports, payments and the audit log, from the **Export CSV** button on each page. Cells that would run as a formula in a spreadsheet are neutralised, passwords and card numbers are never included, and every export is itself written to the audit log. ## The audit log Each change above is recorded with who did it, when, on what, and the details (for example the suspension reason). Entries keep the administrator's email even if that account is later deleted, and the panel offers no way to edit or remove them. ## Two-step sign-in for administrators Set `ADMIN_REQUIRE_2FA=true` and administrators must turn on two-step sign-in (Security in the dashboard) before the admin area opens; until then it answers with a clear message. Strongly recommended in production. Administrators also get an email when their account is suspended or their password or two-step settings change, like any user. ## Reports from visitors Every public profile page has a **Report this profile** link (not shown to the profile's owner). The form takes a reason and an optional note. To stop repeats we keep a **keyed hash** of the reporter's IP address for 24 hours, nothing else, and the page answers the same way whether or not the report was stored. At most six reports a minute are accepted from one address. ## Security notes - The admin area is the same single-page app, but **every** action goes through `/admin/api`, which checks the administrator flag on the server for each request. - Emails of users are visible to administrators, as the job requires. API keys are **never** shown: only a short prefix. - Use a strong, unique password, and consider restricting `/admin` at your web server (for example by IP) as well.