# 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
```
## 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 `