5. API Key Management - nathan-fiscaletti/synful GitHub Wiki

Adding and Removing API Keys

Implementing APIKeyValidation in your RequestHandler

In order to use API Keys with your RequestHandler implementation, you must add the APIKeyValidation Middleware to the RequestHandler.

To do this, override the $middleware property of your RequestHandler and add the APIKeyValidation class to it.

public $middleware = [
    \Synful\Util\Middleware\APIKeyValidation::class,
];

Read more on Middleware here.

Creating an API Key

Note: In order to create an API Key, you must first verify that you have your Primary Synful Database configured in Databases.json.

(See Database Management).

Open a terminal and change directory to your Synful directory.

Run the following command to create an API key.

    $ ./synful -create-key AUTH_HANDLE 'My Name' 10 0 0 0

• This key will be referenced using the authentication handle AUTH_HANDLE.
• The name associated with the API Key will be My Name.
• The API key will have a security level of 10.
• The API key will have an unlimited Rate Limit. (See Rate Limiting)
• The key will initially have no endpoints assigned to it.

The fourth parameter of the -ck or -create-key command is white_list_only. If this is set to a 1 the key will only allow IP addresses whitelisted in it's firewall to use the API Key.

The Private API key will be output when the key is generated. This is what you will use under the Synful-Key header of your request. (See Sending Requests).

Managing the Endpoint Access Array for an API Key

Each API key has an Endpoint Access Array. This works as a list of endpoints that the API key is permitted to access. You can modify this using the following commands.

Adding an endpoint

Run the following command to add an endpoint to allow an API key to access it.

    $ ./synful -end-point-manage add AUTH_HANDLE 'some/endpoint'

You can also add a wildcard to the API keys Endpoint Access Array by using the endpoint *.

    $ ./synful -end-point-manage add AUTH_HANDLE '*'

Removing an endpoint

Run the following command to remove an endpoint from an API key.

    $ ./synful -end-point-manage remove AUTH_HANDLE 'some/endpoint'

Removing an API Key

Run the following command to remove an API key from the Synful Database

    $ ./synful -remove-key AUTH_HANDLE

The API key associated with the authentication handle AUTH_HANDLE will be removed from the system.

Warning: This cannot be undone.

Regenerating API Keys

If you ever want to create a new Private Key for an API key, use the following command.

    $ ./synful -update-key AUTH_HANDLE

A new Private Key associated with the API key will be output.

Minimizing output when creating or updating API keys

When creating an API key, you might want to wrap something else around the CLI. To force Synful to only output the Private Key associated with the API key when using -create-key or -update-key, pass the -output 0 parameter first. All other output will be hidden.

Note: The -output 0 parameter must be passed before all other parameters to work properly.

    $ ./synful -output 0 -update-key AUTH_HANDLE

See CLI Usage Run Through: Other Commands

Modifying the whitelist_only value for an API key

If you have already created an API key but want to update it's whitelist_only value, you can use the following command.

    $ ./synful -white-list-only AUTH_HANDLE 1

This will update the whitelist_only value for the API key to 1.

---

Testing an API Key

You can test an API key from the command line of Synful. You will need the auth handle associated with the API key and the Private Key associated with the API Key.

Run the following command to test authentication using the API key

    $ ./synful -test-auth AUTH_HANDLE a33c3c38ac9873cc6a9876c3

This will test the API key associated with the authentication handle AUTH_HANDLE using the Private Key a33c3c38ac9873cc6a9876c3.

The output should look something like this.

[SYNFUL] [INFO] Authentication for APIKey with auth 'AUTH_HANDLE' has succeeded.
[SYNFUL] [INFO] API Key Embedded Security: Level 10

---

Listing all API keys

You can list all API keys in the system by running the following command.

    $ ./synful -list-keys

---

Enabling and Disabling API keys

You can use the following two commands to enable or disable a key associated with a specific e-mail address.

    $ ./synful -disable-key AUTH_HANDLE

    $ ./synful -enable-key AUTH_HANDLE

Note: When an API key is disabled, it cannot be used.

---

Managing Firewall

Each API key has a firewall associated with it. You can use this to block certain IP addresses from using the API key. If the key has whitelist_only set to 1, this is also how you would add keys to the whitelist for the API key.

Blacklisting an IP address

Run the following command to blacklist an IP address for an API key.

    $ ./synful -firewall-ip AUTH_HANDLE 192.168.10.200 1

This will blacklist the IP address 192.168.10.200 for the API key associated with the authentication handle AUTH_HANDLE.

Whitelisting an IP Address

Run the following command to whitelist an IP address for an API key.

    $ ./synful -firewall-ip AUTH_HANDLE 192.168.10.200 0

This will whitelist the IP address 192.168.10.200 for the API key associated with the authentication handle AUTH_HANDLE.

Note: The last parameter of the -firewall-ip command is the block_value. If you set this to 0, the entry will allow the connection. If you set this to 1, the entry will block the connection.

Removing a Firewall Entry for an IP

Run the following command to fully remove a Firewall Entry for an API key.

    $ ./synful -unfirewall-ip AUTH_HANDLE 192.168.10.200

This will remove the firewall entry for the IP address 192.168.10.200 under the API key associated with the authentication handle AUTH_HANDLE.

Displaying the Firewall for a specific API key

To display the full firewall for an API key, run the following command.

    $ ./synful -show-firewall AUTH_HANDLE

This will output the full firewall listing associated with the API key AUTH_HANDLE.

---

Next: Middleware