HTTP APIs
Functions
syn.request
table syn.request(params: table) [yields]
Makes a RESTful HTTP request.
Request Options
| Option | Description | Default |
|---|---|---|
| Url | The request URL | Required |
| Method | The request method | "GET" |
| Headers | A map of header names to header values | {} |
| Cookies | A map of cookie names to cookie values | {} |
| Body | The request body. Cannot be used with GET or HEAD requests. It might be necessary to specify the Content-Type header when sending JSON or other formats. | nil |
Synapse Headers
In addition to headers provided by the user, Synapse X adds the following:
Note: Syn-Fingerprint and Syn-User-Identifier have been deprecated in favor of the new public key verification system shown below.
| Header | Value | Can Override |
|---|---|---|
| User-Agent | A string in the format "sx/<build_hash>". | Yes |
| Syn-Signature | Public-key authenticated headers, base64-encoded. See below for use. | No |
| Syn-Fingerprint | A string value which uniquely identifies the computer running Synapse X. | No |
| Syn-User-Identifier | A string value which uniquely identifies the current Synapse X user. | No |
Response Table
syn.request returns the following table once the request is complete:
| Key | Description |
|---|---|
| Success | Whether the request succeeded |
| StatusCode | The HTTP status code of the response |
| StatusMessage | A human-readable version of StatusCode |
| Headers | The response headers |
| Cookies | The response cookies |
| Body | The response body |
Public Key Verification
Servers can verify a request was made by Synapse X via the public key verification system, along with syn.crypt.user.sign to verify extra data sent to the server.
To verify a Syn-Signature header, you must use libsodium with the crypto_sign_open function. Pass qgq26x4+4FWdLzRpGZytZfEQJlOeusryQC8ppC2BEVA= (Base64 encoded) as the public key. We will always alert developers and users if this key ever changes.
After signature verification succeeds, you will get a JSON encoded payload with the following fields:
| Field | Description |
|---|---|
| authenticationTime | UNIX timestamp when the user authenticated this instance (UTC). |
| fingerprint | Same as the Syn-Fingerprint legacy header. |
| ipAddress | The IP address that was used to authenticate this instance. Please note this can change if the user was using a mobile network/similar. Can be IPv4 or IPv6. |
| userIdentifier | Same as the Syn-User-Identifier legacy header. |
| userPublicKey | The Base64 encoded public key for this user. You can use this to verify messages that were signed with the syn.crypt.user.sign function. To verify messages, use the libsodium crypto_sign_verify_detached function with this key as the public key. |
| userPromptPublicKey | The Base64 encoded prompt public key for this user. Like the above public key, this can be used to verify messages that were signed with the syn.crypt.user.prompt.sign function. |
Please note that new fields can be added to this JSON payload at any time, so don't rely on the above for your JSON schemas. We will never remove fields without first alerting developers, though.
todo: add NodeJS, PHP, ASP.NET example code and probably move this whole section (Public Key Verification) to a page in the Developer Guide