Skip to main content
POST
/
login
Login
curl --request POST \
  --url https://api.example.com/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "url_code": "<string>",
  "url_pass": "<string>"
}
'
{
  "access_token": "<string>",
  "token_type": "<string>"
}
Authenticate with a password-protected short URL to receive a JWT access token. This token is required to manage the URL (change password, delete, pause, view details, etc.).

​
Request Body

​
url_code
string
required
The short URL code to authenticate with
​
url_pass
string
required
The password for the short URL

​
Authentication Flow

  1. The endpoint looks up the URL code in the database
  2. Verifies that the URL has a password set (rejects unprotected URLs)
  3. Validates the provided password against the stored hash (using PBKDF2-SHA256)
  4. Generates a JWT token containing the URL’s database ID
  5. Returns the access token with a default expiration time
Token Expiration: Access tokens expire after the configured TOKEN_EXPIRE duration (default: 5 minutes). Use the /refresh_token endpoint to obtain a new token before expiration.

​
Response

​
access_token
string
JWT bearer token to use for authenticated endpoints. Include this in the Authorization header as Bearer {token}.
​
token_type
string
Always returns "bearer"

​
Status Codes

  • 200 OK - Authentication successful
  • 400 Bad Request - URL exists but has no password (invalid request)
  • 401 Unauthorized - Invalid credentials (wrong password or URL code doesn’t exist)

​
Request Example

curl -X POST https://api.example.com/login \
  -H "Content-Type: application/json" \
  -d '{
    "url_code": "my-link",
    "url_pass": "secret123"
  }'

​
Response Examples

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

​
Using the Access Token

Once you receive the access token, include it in subsequent authenticated requests: 
curl -X GET https://api.example.com/details \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
This endpoint only works for password-protected URLs. If you try to login to a URL that was created without a password (empty url_pass), you’ll receive a 400 Bad Request error.

​
Security Details

  • Passwords are hashed using PBKDF2-SHA256 before storage
  • JWT tokens are signed with HS256 algorithm
  • Tokens contain the URL’s database _id in the payload
  • Token verification happens on protected endpoints via the authenticate function

Build docs developers (and LLMs) love

Get started for freeTalk to us