Hide-My-Email.info API Documentation
All documents

Authentication

Header-based API access

Account-scoped API endpoints require:

Header Required Value
secret Yes sk1.<accountId>.<...>
x-account-access-id Yes aid1.<...>

Example:

GET /api/v1/aliases HTTP/1.1
Host: Hide-My-Email.info
Accept: application/json
secret: sk1.account123.example-secret-value
x-account-access-id: aid1.example-account-access-id

Public authentication endpoints

These endpoints are available without authentication and do not require secret or x-account-access-id headers.

GET /api/auth/self-registration/access

Checks if self-registration is currently allowed.

Headers: none.

Query parameters: none.

Request body: none.

Response body:

{
  "allowed": true,
  "message": ""
}

Response fields:

Field Type Description
allowed boolean Whether self-registration is currently allowed.
message string Optional message providing additional context.

Response codes:

  • 200 OK
  • 400 Bad Request (if account credentials are provided)

Example:

curl -X GET "http://Hide-My-Email.info/api/auth/self-registration/access" \
  -H "Accept: application/json"

Secret management endpoints

These endpoints are used to manage account secrets.

GET /api/v1/account/secrets

Lists all secrets for the resolved account.

Headers:

Header Required
secret Yes
x-account-access-id Yes

Query parameters: none.

Request body: none.

Response body:

[
  {
    "id": "secret-id",
    "displayName": "sk1.account123....",
    "description": "My automation",
    "isFavorite": false,
    "createdAtUtc": "2026-03-12T09:00:00Z"
  }
]

Response fields:

Field Type Description
id string Secret object identifier.
displayName string Safe display form of the secret.
description string User-provided description.
isFavorite boolean Favorite flag.
createdAtUtc string (date-time) Creation time in UTC.

Response codes:

  • 200 OK
  • 401 Unauthorized

Example:

curl -X GET "http://Hide-My-Email.info/api/v1/account/secrets" \
  -H "Accept: application/json" \
  -H "secret: sk1.account123.example-secret-value" \
  -H "x-account-access-id: aid1.example-account-access-id"

POST /api/v1/account/secrets/generate

Creates a new secret.

Headers:

Header Required
secret Yes
x-account-access-id Yes
Content-Type: application/json Yes

Query parameters: none.

Request body:

{
  "description": "My automation"
}

Request fields:

Field Type Required Description
description string Yes Description shown in secret lists.

Response body:

{
  "success": true,
  "message": "Secret created.",
  "secret": {
    "id": "secret-id",
    "displayName": "sk1.account123....",
    "description": "My automation",
    "isFavorite": false,
    "createdAtUtc": "2026-03-12T09:00:00Z"
  },
  "plainSecret": "sk1.account123...."
}

Response fields:

Field Type Description
success boolean Operation status.
message string Human-readable result.
secret object or null Created secret metadata.
plainSecret string or null Full secret value. Returned only at creation time.

Response codes:

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized

Example:

curl -X POST "http://Hide-My-Email.info/api/v1/account/secrets/generate" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "secret: sk1.account123.example-secret-value" \
  -H "x-account-access-id: aid1.example-account-access-id" \
  -d "{\"description\":\"My automation\"}"

`PUT /api/v1/account/secrets/

Updates the favorite flag.

Headers:

Header Required
secret Yes
x-account-access-id Yes
Content-Type: application/json Yes

Path parameters:

Parameter Type Required Description
secretId string Yes Secret identifier.

Request body:

{
  "isFavorite": true
}

Request fields:

Field Type Required Description
isFavorite boolean Yes New favorite state.

Response body:

{
  "success": true,
  "message": "Secret updated.",
  "secret": {
    "id": "secret-id",
    "displayName": "sk1.account123....",
    "description": "My automation",
    "isFavorite": true,
    "createdAtUtc": "2026-03-12T09:00:00Z"
  }
}

Response codes:

  • 200 OK
  • 400 Bad Request
  • 401 Unauthorized
  • 404 Not Found

Example:

curl -X PUT "http://Hide-My-Email.info/api/v1/account/secrets/secret-id/favorite" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "secret: sk1.account123.example-secret-value" \
  -H "x-account-access-id: aid1.example-account-access-id" \
  -d "{\"isFavorite\":true}"

`DELETE /api/v1/account/secrets/

Deletes a secret.

Headers:

Header Required
secret Yes
x-account-access-id Yes

Path parameters:

Parameter Type Required Description
secretId string Yes Secret identifier.

Request body: none.

Response body: none.

Response codes:

  • 204 No Content
  • 401 Unauthorized
  • 404 Not Found

Example:

curl -X DELETE "http://Hide-My-Email.info/api/v1/account/secrets/secret-id" \
  -H "secret: sk1.account123.example-secret-value" \
  -H "x-account-access-id: aid1.example-account-access-id"

OAuth token endpoints

These endpoints allow issuing short-lived access tokens and refresh tokens for use in OAuth-style integrations. They operate on browser sessions or existing tokens and do not use the secret / x-account-access-id header pair.

POST /api/oauth/token

Issues a new access/refresh token pair for the currently authenticated browser session.

Requires an active browser session (cookie-based). Not usable with secret header authentication.

Request body: none.

Response fields:

Field Type Description
accessToken string Short-lived access token.
refreshToken string Long-lived refresh token.

Response codes:

  • 200 OK
  • 401 Unauthorized

POST /api/oauth/login

Exchanges a valid access token for a browser session.

Request body:

{ "accessToken": "..." }

Response fields:

Field Type Description
success boolean Operation status.
message string Human-readable result.
session object Current browser session state.
session.isAuthenticated boolean Whether the browser session is authenticated.
session.code string or null Authenticated account code for the active browser session.
session.expiresAtUtc string (date-time) or null Session expiration time in UTC.
mobileCredential object or null Mobile auth credential payload when returned. Usually null for this endpoint.
mobileCredential.code string Account code for mobile auth.
mobileCredential.authKey string Generated mobile auth key.
persistentTokens object or null OAuth token pair when returned. Usually null for this endpoint.
persistentTokens.accessToken string Access token.
persistentTokens.tokenType string Token type, for example Bearer.
persistentTokens.expiresInSeconds integer Access token lifetime in seconds.
persistentTokens.accessTokenExpiresAtUtc string (date-time) Access token expiration time in UTC.
persistentTokens.refreshToken string Refresh token.
persistentTokens.refreshTokenExpiresInSeconds integer Refresh token lifetime in seconds.
persistentTokens.refreshTokenExpiresAtUtc string (date-time) Refresh token expiration time in UTC.
retryAfterSeconds integer or null Cooldown hint when applicable. Usually null for this endpoint.
actionUrl string or null Optional follow-up action URL. Usually null for this endpoint.
actionLabel string or null Optional follow-up action label. Usually null for this endpoint.

Response codes:

  • 200 OK
  • 401 Unauthorized

POST /api/oauth/refresh

Issues a new token pair using a valid refresh token.

Request body:

{ "refreshToken": "..." }

Response fields: same as POST /api/oauth/token.

Response codes:

  • 200 OK
  • 401 Unauthorized

POST /api/oauth/validate

Validates an access token and/or refresh token without issuing new tokens.

Request body:

{ "accessToken": "...", "refreshToken": "..." }

Response fields:

Field Type Description
accessTokenValid boolean Whether the access token is currently valid.
refreshTokenValid boolean Whether the refresh token is currently valid.

Response codes:

  • 200 OK
© 2026 PrivacyGuard.company. All rights reserved.