API Guide

There is no separate developer screen: your API identity is your own account.

1. 1
   Open your account

   The email and password you use in the panel are also your API credentials. You do not need to generate a separate key.
2. 2
   Get a token

   POST your credentials to the signin endpoint; the response field data.token is your session token.
3. 3
   Add it to the header

   Carry the token on every following request in the Authorization: Bearer header. No cookies are sent.
4. 4
   Read the envelope

   Look at the result field in the body, not just the HTTP status: on ok you read data, on error you read error.code.

The address below is derived from the domain this page is served from — you can copy it as is.

curl -X POST 'https://sosyalasistan.app/api/v1/signin' \
  -H 'Content-Type: application/json' \
  -d '{"mail": "[email protected]", "password": "your-password"}'

{
  "result": "ok",
  "data": {
    "token": "7f1c…",
    "user": { "id": "7312904418291712", "mail": "[email protected]" }
  }
}

curl 'https://sosyalasistan.app/api/v1/me' \
  -H 'Authorization: Bearer 7f1c…'

{
  "result": "error",
  "error": { "code": "UNAUTHENTICATED", "message": "Oturum yok" }
}

Tokens live in Redis and are invalidated on sign-out; the signout endpoint accepts POST or DELETE.

Every live resource and the credential each one needs. The list is locked against the routing registry; only the router internals and one provider callback stay out.

The verb mapping is the same for every resource: GET to list and read, POST to create, PUT to update, DELETE to remove. The response tells you which verbs a resource supports — an unsupported verb returns 405.

no auth

No header required; the request works as-is.

Bearer token

Send the data.token value from the POST /api/v1/signin response in the Authorization: Bearer … header.

admin permission

Requires an administrative identity and permission; a customer token does not pass — depending on the endpoint you get 401 or 403.

operations credential

Requires a separate monitoring credential (an X-Metrics-Token header or an allow-listed IP); a customer token does not pass, and with no configuration it returns 401.

callback

You are not the caller: the request is authenticated by the provider signature or by a single-use link sent in e-mail.

The envelope is the same for every resource: a successful response carries result: "ok" plus data, an error carries result: "error" plus error.code. Field lists are printed further down this page for the resources listed there; for the rest, the response to your own request is the authority on field names.

error.code is always present in an error body. Branch on the codes you recognise and fall back to the HTTP status class for everything else: an endpoint may answer with a code that is more specific than the generic set below.

Endpoint-specific codes

These rows are not hand-written either: the code is read from the file that actually emits it and the status from the same map the server uses. Your very first request can already return a code that is not in the table above.

The table above is the generic set, not the whole list: 413 codes are mapped to a status in our code and further codes are produced without a mapping — an unmapped code comes back with the default 400. Handle a code you do not recognise by its HTTP status class, and never read a status as if it implied the generic code.

These field lists are not hand-written: they are read from the validation group that filters the endpoint's own requests, so what the gate enforces is what you see.

Three resources are listed here for now; the field list for the remaining 30 has not been written yet. Rules appear in the validator's own notation: max:255 means at most 255 characters, in:a,b means only the listed values.

Every delivery we send to your endpoint is signed. The headers below are printed from the constants in our code, not typed by hand.

1758412800.{"event":"order.created",…}

Verify like this: build the base string, compute HMAC-SHA256 with your subscription secret, prefix the lowercase hex with v1=, and compare in constant time. The timestamp sits inside the signature, so you can drop a stale delivery with your own abs(now − timestamp) threshold.

• How does versioning work?

  The version travels in the address. Every API response returns the X-Min-Version and X-Latest-Version headers; today both are 1.
• Which header should carry the token?

  The preferred form is Authorization: Bearer <token>. The server also accepts the X-Auth-Token header. External integrations should not rely on cookies; always send the token in a header.
• How are list endpoints paginated?

  With the page and per_page query parameters; per_page defaults to 20 and is capped at 100. The page information comes back in the meta.pagination field.
• Why do record IDs come back as strings?

  IDs are 64-bit integers and JavaScript loses precision at that width. They are therefore returned as strings in JSON; compare them as strings.
• What format do date fields use?

  Every date field is a unix epoch integer in seconds. No textual date format is returned.
• Is the response always JSON?

  Yes — every response, error paths included, is served with the application/json header. If you get HTML back, the request never reached the API; check the version prefix in the address.