Authentication

Catalytic SDK requests are authenticated using Access Tokens. The easiest way to create a new Access Token, or to manage your existing Access Tokens is from your Account page in the Catalytic Web App. However, you can also manage your tokens from the SDK itself. Here you will find a quick guide to managing your Access Tokens in the web app or with the SDK.

Creating your first token

The easiest way to create a new authentication token is to go to your Account page in the Catalytic Web App. You can view and manage all of your tokens from that screen.

As shown in the screenshot below, when you create a new token, you can give your token a nickname that represents where the token will be used from.

When you create your token, you will have a chance to copy or download your token. This will be the only time you can get your token, so you must be sure to download or copy it before closing this window. Besides some metadata, Catalytic only stores the hash of your token's secret. This ensures that even with a decrypted copy of our database, an attacker could not authenticate with your token through the SDK.

You now have a few options for configuring the SDK to use that token.

• Environment Variable
• Default Access Token File
• Named Access Token File
• Custom storage
• Hard coded

Environment Variable

First, copy your token string by clicking on the Copy button, then save the copied value as the CATALYTIC_TOKEN environment variable.

Default Access Token File

First, download your token by clicking on the Download button, then save the file as $HOME/.catalytic/tokens/default

Using your Default Access Token

You can use an Access Token set in the environment or the default Access Token file by instantiating a CatalyticClient with an empty constructor. An empty constructor will first try to load the Access token from the CATALYTIC_TOKEN environment variable. If that is not set, it will try to read them from $HOME/.catalytic/tokens/default

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use Catalytic\SDK\CatalyticClient;

$catalytic = new CatalyticClient();

Named Access Token File

If you want to use multiple Access Tokens from within the same application, or use different Access Tokens with different applications running under the same user account on your machine, you can name your saved Access Tokens and load them dynamically.

Simply name your downloaded Access Token file something other than default when you save it to your $HOME/.catalytic/tokens/ directory. You can then pass that name to the Client constructor.

For example, you may want to run your application in both your production and UAT teams. If you saved your UAT Access Token to $HOME/.catalytic/tokens/uat, you could load both like this:

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use Catalytic\SDK\CatalyticClient;

$catalyticUat = new CatalyticClient("uat");
$catalyticProd = new CatalyticClient("prod");

You don't have to use the default location for your Access Token files. If you want to use some other path, you can pass the location to the CatalyticClient constructor, like this:

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use Catalytic\SDK\CatalyticClient;

$catalytic = new CatalyticClient('path/to/tokens/my-token');

Custom Storage or Hard-Coded

You can also store your tokens anywhere you like as long as you can load them into a string in your application. For example, you may want to store your Access Token in a Secrets Vault. Simply save the copied token string into your storage system. Then in your application, retrieve that string from your storage system and initialize your Client with the token directly. You can also simply hard-code your token string, though that's not recommended for most production scenarios. For example:

<?php

require_once(__DIR__ . '/vendor/autoload.php');

use Catalytic\SDK\CatalyticClient;

$catalytic = new CatalyticClient('xyz123');

Access Token Lifecycles

Once you have several Access Tokens, using a descriptive name will make it easier to know which token you want to revoke. For example, you might have one token for development named "MacBook Pro 2016" and another for production named "AWS Production". If you later replace your laptop, you know you can safely revoke your "MacBook Pro 2016" token without risk of deleting the token you use for production. Your tokens never expire, so be sure to revoke any that are no longer in use.

Creating Access Tokens from the SDK

In addition to creating and managing your tokens in the Catalytic Web App, you can create and manage your tokens through the Catalytic SDK. Creating and managing user tokens is done through the AccessTokens client as shown in the examples below. In addition to viewing and revoking existing tokens, the SDK provides two methods to create new tokens:

Create a new Access Token using your email and password

Unless your team is configured with SSO (in which case, see the note below), you can use your email and password to create a new Access Token which you can then use for all subsequent SDK requests.

<?php

/*
 * This example demonstrates creating a new Access Token using your
 * email and password
 */

require_once(__DIR__ . '/vendor/autoload.php');

use Catalytic\SDK\CatalyticClient;

$catalytic = new CatalyticClient();

$accessToken = $catalytic->accessTokens()->create(
                "your-team.pushbot.com",
                "your-email",
                "your-password");

$userHomeDir = defaultposix_getpwuid(posix_getuid());
$file = new SplFileObject($userHomeDir, 'w');
$file->fwrite($accessToken->getToken());

$catalytic->setAccessToken($accessToken);

// You are now authenticated and ready to use the Catalytic SDK
// The above only needs to be done once. Now that your Access Token
// is saved as the default Access Token, you can configure the SDK
// to use those:
$catalytic = new CatalyticClient();

🚧

Does your team use SSO?

If your Catalytic team has SSO enabled, you cannot use the email and password method to create a new token since you do not have a password enabled for your Catalytic login. Instead you must use the createWithWebApprovalFlow method below.

Create a new Access Token using the web approval flow

For interactive applications, rather than passing your email and password to authenticate your request for an Access Token, you can instead request an Access Token through the SDK, but approve them interactively by logging into your Catalytic account in a web browser. This is similar to OAuth flows where the user is redirected to their identity provider to approve the request.

<?php

/*
 * This example demonstrates creating a new Access Token using tbe
 * web approval flow
 */

require_once(__DIR__ . '/vendor/autoload.php');

use Catalytic\SDK\CatalyticClient;
use Catalytic\SDK\Search\Where;

$catalytic = new CatalyticClient();

$accessToken = $catalytic->accessTokens()->createWithWebApprovalFlow(
                "your-team.pushbot.com");

// A human will need to manually approve this request via this URL
$approvalUrl = $catalytic->accessTokens()->getApprovalUrl($accessToken);

// Wait for approval
$catalytic->accessTokens()->waitForApproval($accessToken);

// Save the token to the default Access Token file
$userHomeDir = defaultposix_getpwuid(posix_getuid());
$file = new SplFileObject($userHomeDir, 'w');
$file->fwrite($accessToken->getToken());

$catalytic->setAccessToken($accessToken);

// You are now authenticated and ready to use the Catalytic SDK
// The above only needs to be done once. Now that your Access Token
// is saved as the default Access Token, you can configure the SDK
// to use those:
$catalytic = new CatalyticClient($ccessToken->getDefault());

When the approval URL is opened in the browser, you will first be asked to log in if you are not already logged in to your Catalytic team. Once you are logged in, you will see a screen like the following, asking you to approve of the access token request.

The $catalytic->accessTokens()->waitForApproval($accessToken) call will block until the user has approved or canceled the request. If the request is canceled, the waitForApproval will throw an UnauthorizedException.