|
1 | 1 | --- |
2 | | -sidebar_position: 4 |
| 2 | +sidebar_position: 3 |
3 | 3 | --- |
4 | 4 |
|
5 | 5 | import AppUrl from '@site/src/components/AppUrl'; |
6 | 6 |
|
7 | 7 | # Authentication |
8 | 8 |
|
9 | | -This page outlines the necessary steps and protocols for securely interacting with our API, ensuring that your data remains safe and your transactions are securely processed. |
| 9 | +This section explains how to authenticate requests to the Stakely Staking API and securely interact with its endpoints. |
10 | 10 |
|
11 | | -## Auth |
12 | 11 |
|
13 | | -To use the Staking API, you must be registered with an account on <AppUrl />. If you don't have an account yet, you can <AppUrl path="/sign-up">register here</AppUrl>. |
| 12 | +## Create API keys |
14 | 13 |
|
15 | | -Once registered, <AppUrl path="/sign-in">login into your account</AppUrl>, you'll have access to all the products that Stakely offers, all using the same simplified account. |
| 14 | +To use the Staking API, you must have an account on <AppUrl />. If you do not have one yet, you can <AppUrl path="/sign-up">register here</AppUrl>. |
16 | 15 |
|
17 | | -Manage your API keys in the Staking API dashboard at <AppUrl path="/staking-api" />. The dashboard provides a simple interface to create new keys, view existing keys, and delete keys you no longer need. |
| 16 | +Once registered, <AppUrl path="/sign-in">log in to your account</AppUrl>. A single account provides access to all Stakely products, including the Staking API. |
18 | 17 |
|
19 | | -## Using the API Keys |
| 18 | +API keys are managed from the Staking API dashboard at <AppUrl path="/staking-api" />. From there, you can create new keys, view existing ones, and revoke keys when no longer needed. |
20 | 19 |
|
21 | | -To access the crafting and reporting endpoints, you must authenticate using API keys generated through the Staking API web app at <AppUrl />. |
| 20 | + |
| 21 | +## Using API keys |
| 22 | + |
| 23 | +All API requests must be authenticated using an API key generated through the Staking API dashboard. |
22 | 24 |
|
23 | 25 | Include your API key in the `X-API-KEY` header with every request: |
| 26 | + |
24 | 27 | ```http |
25 | 28 | X-API-KEY: your-api-key-here |
26 | 29 | ``` |
27 | 30 |
|
28 | | -For examples and pre-created code snippets in various programming languages, which will help you integrate our services smoothly, please refer to our API schema available [here](/staking-api/api-reference). |
| 31 | +Examples and ready-to-use code snippets in different programming languages are provided in later sections of the documentation, within each network-specific integration guide. |
| 32 | + |
| 33 | + |
| 34 | + |
| 35 | +## Response signature verification (optional) |
29 | 36 |
|
30 | | -## Security and Verification |
| 37 | +As an additional security measure, each HTTP response includes a cryptographic signature in the `x-signature` response header. This signature allows clients to verify the integrity and authenticity of the response payload. |
| 38 | + |
| 39 | +The signature is generated by signing the SHA-256 hash of the HTTP response body using Stakely’s RSA private key. Clients can verify the signature using the corresponding RSA public key provided below. |
31 | 40 |
|
32 | | -Ensuring the security of all transactions and data exchanges remains our top priority. To accomplish this, we have implemented a method where the signature of each HTTP response can be found in the header under the name `x-signature`. This signature is the SHA256 hash of the HTTP response body, signed using the Elliptic Curve Digital Signature Algorithm (ECDSA) with the SECP256k1 curve. To verify the integrity and authenticity of the data received, you must use the corresponding public key, which is readily accessible on the expandable bellow. |
33 | 41 | <details> |
34 | | - <summary>**PUBLIC KEY**</summary> |
35 | | - <div> |
36 | | - <div>Copy this value for signature verification:</div> |
37 | | - <br/> |
38 | | - ```markup |
39 | | - -----BEGIN PUBLIC KEY----- |
40 | | - MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2TpKOJfmku7aEIrKaCMM |
41 | | - xjA10UCixAryVsB+PIoLKTEsUiNfctwbeXcpQuPOit9H7by+ezgg/A4SCog/Dtc7 |
42 | | - fTp4Gnnq/adLNDllMeKoQCeIz/3N7TqItr+74NTAm6TkwR4lriIy/XiDpIak530f |
43 | | - 8ZXFnmQTz3Cffbio3A9DhgwC5OWjSgkYdU35Rti36OGM6pnPlipxm7KD/9ddjc+H |
44 | | - vRY8o6kbp8Cy9QsXZqivHVvcFQ61gl8TMpgcziNgI+tDiof/SM6x6KGxuGT3s40J |
45 | | - TZ0g98GKgynkRW22OPfK3vP1FZ0UmIRJ6tAWYTNntGjLM+vM1OOsGk+5BmEkxy/B |
46 | | - HwIDAQAB |
47 | | - -----END PUBLIC KEY----- |
48 | | - ``` |
49 | | - </div> |
| 42 | + <summary><strong>Public key</strong></summary> |
| 43 | + |
| 44 | +```text |
| 45 | +-----BEGIN PUBLIC KEY----- |
| 46 | +MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2TpKOJfmku7aEIrKaCMM |
| 47 | +xjA10UCixAryVsB+PIoLKTEsUiNfctwbeXcpQuPOit9H7by+ezgg/A4SCog/Dtc7 |
| 48 | +fTp4Gnnq/adLNDllMeKoQCeIz/3N7TqItr+74NTAm6TkwR4lriIy/XiDpIak530f |
| 49 | +8ZXFnmQTz3Cffbio3A9DhgwC5OWjSgkYdU35Rti36OGM6pnPlipxm7KD/9ddjc+H |
| 50 | +vRY8o6kbp8Cy9QsXZqivHVvcFQ61gl8TMpgcziNgI+tDiof/SM6x6KGxuGT3s40J |
| 51 | +TZ0g98GKgynkRW22OPfK3vP1FZ0UmIRJ6tAWYTNntGjLM+vM1OOsGk+5BmEkxy/B |
| 52 | +HwIDAQAB |
| 53 | +-----END PUBLIC KEY----- |
| 54 | +``` |
| 55 | + |
50 | 56 | </details> |
51 | | -This approach ensures that the data remains unaltered during transmission, thereby preserving the security and integrity of your interactions. While verification of the signature on the client side is optional, we encourage its implementation as an additional measure to further ensure the authenticity and integrity of the data received. |
52 | 57 |
|
53 | | -Here is an example code on how you can verify returned signature: |
| 58 | +Signature verification on the client side is optional but recommended, especially for integrations requiring additional guarantees around data integrity. |
54 | 59 |
|
55 | | -- Node.js Example: |
56 | | - - Replace `publicKey` with the provided Staking API public key. |
57 | | - - Replace `data` with the returned JSON payload at the request. |
58 | | - - Replace `signature` with the returned signature string value located at `x-signature` header |
59 | 60 |
|
| 61 | +### Example: signature verification in Node.js |
60 | 62 |
|
61 | 63 | ```javascript |
62 | 64 | const crypto = require('crypto'); |
63 | 65 |
|
64 | 66 | function verifySignature(publicKey, data, signature) { |
65 | | - const verifier = crypto.createVerify('RSA-SHA256'); |
66 | | - verifier.update(data); |
67 | | - return verifier.verify(publicKey, signature, 'base64'); |
| 67 | + const verifier = crypto.createVerify('RSA-SHA256'); |
| 68 | + verifier.update(data); |
| 69 | + return verifier.verify(publicKey, signature, 'base64'); |
68 | 70 | } |
69 | 71 |
|
70 | | -// Example usage: |
71 | | -const publicKey = '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----'; // Your public key here |
72 | | -const receivedData = '{"data":"Example payload"}'; // JSON string as received from the server |
73 | | -const receivedSignature = 'received_signature_from_header'; // Signature received from the X-Signature header |
| 72 | +// Example usage |
| 73 | +const publicKey = '-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----'; |
| 74 | +const receivedData = '{"data":"Example payload"}'; |
| 75 | +const receivedSignature = 'signature-from-x-signature-header'; |
74 | 76 |
|
75 | 77 | const isValid = verifySignature(publicKey, receivedData, receivedSignature); |
76 | 78 | console.log('Is the signature valid?', isValid); |
| 79 | +``` |
| 80 | + |
| 81 | + |
| 82 | +### Next steps |
77 | 83 |
|
78 | | -``` |
| 84 | +Once authenticated, you can start interacting with the network-specific staking endpoints described in the following sections. |
0 commit comments