Hipcall API Key and Your First Request

Part A: Discovery (findings on the DEMO environment)

1. Menu path and URLs

• Sign in: https://use.hipcall.com.tr/
• Main menu path: Settings > Developer (https://use.hipcall.com.tr/portal/settings/?section=developer)
• API tab: Settings > Developer > API (https://use.hipcall.com.tr/portal/settings/developer/api-tokens/)
• Creating a key: the “New” button (https://use.hipcall.com.tr/portal/settings/developer/api-tokens/new/)

2. Required and optional fields

• Creating an API key asks for a “Name” and an “Expiry date”.
• There are no optional fields; both are required. You cannot continue with either one left empty.
• Expiry rule: the system assigns a 1-year validity by default. You can pick up to a maximum of 3 years. If you try to pick a date further out than 3 years, the system silently pulls it back to 1 year.

3. Visibility after saving

• Once the key is created, the screen shows the key itself, an “OK” button, and this warning:

  “Please store this secret key somewhere safe and accessible. For security reasons you won’t be able to view it again through your Hipcall account. If you lose this secret key, you’ll need to generate a new one.”

• After that page is closed, the full API key can never be displayed again. The list screen shows a masked version instead of the full string.

4. Deleting a key

• Path: Settings > Developer > API > [Token name] > Delete
• When you start the deletion, the system shows this warning:

  “This API secret key will be deleted immediately. API requests made using this key will be rejected, which could cause any systems still depending on it to break. Once revoked, you’ll no longer be able to view or modify this API key.”

• The screen shows the key’s name, its last 4 characters, and “Delete” / “Cancel” buttons. Once confirmed, the key is revoked instantly.

5. Permission restrictions

• Users with the “Admin” and “Owner” roles have full access to the “Settings > Developer” menu and the API settings.
• Users with the “Standard” and “Supervisor” roles have no access to this menu; it is not rendered on their screen at all.

Part B: Verification (with curl, by measuring)

B1. Find the right address

The addresses listed in the reference were tested:

Attempt 1 (api.hipcall.com):

curl -sS -i https://api.hipcall.com/api/v3/profile

Output:

curl: (6) Could not resolve host: api.hipcall.com

Attempt 2 (use.hipcall.com):

curl -sS -i https://use.hipcall.com/api/v3/profile

Output:

401 Unauthorized (region/server mismatch).

Correct address: for DEMO accounts located in Türkiye, the endpoint was found to be https://use.hipcall.com.tr/api/v3/profile.

B2. Request without a key

curl -sS -i https://use.hipcall.com.tr/api/v3/profile

Output summary:

• HTTP status code: 401 Unauthorized
• Response body:

{"errors":{"detail":"Authentication required. Provide either OAuth Bearer token or API token."}}

B3. Request with a malformed key

curl -sS -i -H "Authorization: Bearer bu-anahtar-sahte" https://use.hipcall.com.tr/api/v3/profile

Output summary:

• HTTP status code: 401 Unauthorized
• Response body (different from B2):

{"errors":{"detail":"Not authorized. Check your API token is valid and not expired."}}

B4. Request with a valid key

curl -sS -i -H "Authorization: Bearer $HIPCALL_API_TOKEN" https://use.hipcall.com.tr/api/v3/profile

Output summary:

• HTTP status code: 200 OK
• Returned fields: under the data object: user, permissions, capabilities, account, roles and subscription.

Full response body (masked):

{"data":{"user":{"id":4200,"owner":true,"suspended":false,"state":"available","title":null,"email":"ornek@firma.com","locale":"tr_TR","timezone":"Europe/Istanbul","created_at":"2026-07-21T10:55:30","full_name":"Ahmet Y.","numbers":[{"id":939,"name":"Alt yönetici","number":"+90850XXXXXXX","country":"TR"},{"id":938,"name":"Üst yönetici","number":"+90850XXXXXXX","country":"TR"}],"default_number":{"id":938,"name":"Üst yönetici","number":"+90850XXXXXXX","country":"TR"},"first_name":"Ahmet","last_logged_in":"2026-09-15T13:10:07","last_name":"Y.","phone_countries":["AR","AU","BR","CA","CN","FR","DE","IN","ID","IT","JP","MX","RU","SA","ZA","TR","GB","US","KR"],"phone_prefix":"TR","avatar_url":null},"permissions":[],"capabilities":{"cdr":{"label_feature":true,"note_feature":true},"features":{"api":true,"ticket":true,"webhook":true,"deal":true,"automation":true,"smartbcc":true},"contact_center":{"label_feature":true,"note_feature":true}},"account":{"id":1412,"name":"Demo","status":"active","options":{"auto_available_on_login":false,"auto_away_on_logout":false},"locale":"tr_TR","timezone":"Europe/Istanbul","created_at":"2026-07-21T10:55:30","contact_center":{"b2b":true},"limits":{"max_channel":5},"slug":null},"roles":[],"subscription":{"id":1189,"starts_at":"2026-07-21T23:59:59","canceled_at":null,"ends_at":"2027-07-21T23:59:59","limit_cdr_call_history_mounth_count":3,"limit_phone_number_count":5,"limit_phone_simultaneous_call_count":30,"limit_user_count":50,"trial_ends_at":"2026-07-21T23:59:59","plan_name":null}}}

B5. The format of the key

• When the key copied from the screen is added to the request as-is, the API returns 200 OK and works without issue.
• When the SFMyNTY. prefix is manually prepended to the copied key, the API still returns 200 OK.
• Conclusion: the system accepts both formats (with and without the prefix) as valid.

B6. Response headers

A successful request returns rate limit information in its headers:

• x-ratelimit-limit: 60 (60 requests per minute are allowed).
• x-ratelimit-remaining: 59 (requests left).
• x-ratelimit-reset: 1789490696 (timestamp at which the limit resets).

---

Findings

1. Endpoint mismatch: the api.hipcall.com and use.hipcall.com addresses listed in the official API reference are not valid for accounts in Türkiye (DEMO). The correct root address is use.hipcall.com.tr.
2. Flexible key format: there is no single correct way to use the key taken from the dashboard. Both the raw key and the key with SFMyNTY. prepended are accepted as authorized.

---

Flow of the first successful request

sequenceDiagram
    participant D as Developer
    participant P as Hipcall Dashboard
    participant A as Hipcall API (use.hipcall.com.tr)

    D->>P: Go to Settings > Developer > API
    D->>P: Create a new key
    P-->>D: Key is shown on screen (once only)
    Note over D,P: Once the page is closed the key can never be read in full again
    D->>A: GET /api/v3/profile (Header: Authorization: Bearer $HIPCALL_API_TOKEN)
    A-->>D: 200 OK + profile data (JSON) + x-ratelimit headers