Personal Access Applications
Personal Access Apps are authenticated by public/private key encryption, using signed asymmetric ES256 JWTs that you generate.
If you're familiar with Bitcoin, this authentication scheme may sound familiar. A Bitcoin transaction is signed by your private key, and authenticated by others using your public key, from which the spending address is derived.
The Swan API uses the same mechanism to secure your API calls. You'll generate a private key, which you must keep safe. You'll upload the corresponding public key to our API servers.
This method is substantially more secure than password or token based APIs, because the secret (private key) will never leave your posession and is generated locally (or within an HSM).
Steps to use the Swan API:
- Generate your public/private key pair (once)
- Submit the Public Key on your Swan Dashboard (once)
- Generate a JWT, sign it, and add it to your request header (on every request)
Generate your keys for development​
Generate a private key (private.pem) and public key (public.pub) derived from the private key.
You'll need the openssl library. On Mac OSX, this can be obtained via brew install openssl.
openssl ecparam -name secp256k1 -genkey -noout -out private.pem
openssl ec -in private.pem -pubout -out public.pem
Note: this is designed to get you started quickly for development. Please read securing private keys for a better option.
Submit your Public Key to the Swan Dashboard​
Now, please visit your Swan Developer Dashboard to upload this key and create your Personal Access App. Copy the AppId provided. Ensure that the public key contains the "BEGIN" and "END" blocks.
Generate a signed JWT for every API call​
For every API call you make, you'll generate a JWT and supply it in the
Bearer header. Each API call you make will have a unique JWT, preventing a
replay attack.
It is important that the JWT you supply has a very short expiry time and a
jti unique uuid. Please follow the example below. We provide an example using
NodeJS, but this should be easy to translate to most languages using any off
the shelf jwt library.
This example shows you how to create a signed JWT and execute a market buy:
Securing Private Keys​
You must not allow your private key to be exposed. Protect it in the same way you protect your Bitcoin keys.
If you suspect that your private key has been compromised, you can delete the app from your dashboard in order to suspend access.
For production use, we encourage you to take this one step further, and generate your private key inside of a HSM (Hardware Security Module) so that not even you have direct access to the private key.
The swan buyer sample code provides instructions on generating KMS keys, where the private key will never be in your posession. It also shows you how to use KMS to sign the api calls securely.
If an HSM is not available, store your private key in a suitable secrets manager such as AWS Secrets Manager, Hashicorp Vault, or similar.
Scopes​
The following scopes are available for Client Access Apps. We are in the process of exposing more APIs. Additional functionality is available by request to integrations@swan.com.
| Description | Scope |
|---|---|
| Make Buys | write:trades,read:trade_quotes |
| Get pricing | read:trade_quotes |
| List your payment methods (last4 digits of bank only) | read:payment_methods |