Download the PHP package slashid/php without Composer

SlashID SDK

Installation

Install this library with composer:

Usage

Instantiating the SDK

First, create a SDK instance, informing the following:

• $environment, either sandbox or production
• $organizationId, your organization's ID. You'll find it in your SlashID console (https://console.slashid.dev/ for production, https://console.sandbox.slashid.dev/ for sandbox), in the "Settings" tab, on the top of the page.
• $apiKey, your organization's ID. You'll also find it in your SlashID console, in the "Settings" tab, at the very bottom of the page.

Making requests

You can do direct web service requests with the methods ->get, ->post, ->patch, ->put, ->delete.

GET request

The get method can be used for both index-style endpoints and get-one endpoints.

You can use the second argument to specify a query to the endpoint:

POST, PATCH, PUT requests

For POST, PATCH, PUT requests, you need to pass a body as a second parameter:

DELETE requests

DELETE requests don't return anything:

Some endpoints require a query as well:

getClient()

The methods $sdk->get(), $sdk->post(), $sdk->patch(), $sdk->put() and $sdk->delete() expect sending and receiving JSON, but some endpoints have special requirements, e.g. GET /persons/bulk-import (Fetch the import CSV template) will return a CSV and requires a Accept: text/csv header.

For those cases, you can use $sdk->getClient() to retrieve the underlying GuzzlePHP client with the proper credentials preset, for instance:

Exceptions

The following exceptions may be thrown in case of errors during the connection:

• \SlashId\Php\Exception\BadRequestException when the API returns a 400 error, meaning that the data you've sent to the request is malformed or missing the required information.
• \SlashId\Php\Exception\UnauthorizedException when the API returns a 401 error, meaning that either the Organization ID or API key is wrong. In this case, check your credentials.
• \SlashId\Php\Exception\AccessDeniedException when the API returns a 403 error, meaning you are not allowed to access a resource.
• \SlashId\Php\Exception\InvalidEndpointException when the API returns a 404 error due to you requesting an endpoint that does not exist. In this case, check the API reference.
• \SlashId\Php\Exception\IdNotFoundException when the API returns a 404 error on a valid endpoint, meaning the ID you've requested does not exist. This exception will happen on requests that include an ID in the URL, such as /persons/1111-1111-1111.
• \SlashId\Php\Exception\ConflictException when the API returns a 409 error, usually meaning you are trying to create a duplicated entity (e.g. a person with an email already belonging to an existing person). In this case, check the API reference to see if there is an idempotent version of the endpoint.
• \GuzzleHttp\Exception\ClientException when the API returns any other 4xx error.
• \GuzzleHttp\Exception\BadResponseException when the API returns any 5xx error.
• Some implementation of \GuzzleHttp\Exception\GuzzleException if there is any other kind of error during the connection with the API server.

All of \SlashId\Php\Exception exceptions are descendants of \GuzzleHttp\Exception\BadResponseException, which means that you can use the following methods to learn about the causes of the error:

\SlashId\Php\PersonInterface / \SlashId\Php\Person

The Person class is very useful for representing Person information coming from the /persons/{id} endpoint.

You can instantiate a class with Person::fromValues, using the response from the endpoint.

With that, you have several functions to read the person's data:

We also have the respective setters:

:warning: Note that the methods in this class will NOT update the data in SlashID servers. To do that, you must make a request PATCH /persons/:person_id or a request PUT /persons.

Attributes

The person attributes in SlashID are stored in buckets. They are represented in this SDK by the following constants.

:warning: Be careful not to expose "NO_ACCESS" attributes to the end-user.

In the Person, the attributes are accessible with the following methods:

The attributes can also be set:

:warning: Note that the methods in this class will NOT update the data in SlashID servers. To do that, you must do a request PUT /persons/:person_id/attributes or /persons/:person_id/attributes/:bucket_name.

Groups

The Person class also has three useful methods to test the person's groups:

Migration Abstraction

The migration abstraction is a class to bulk importing users.

To import users, you must first create an array of \SlashId\Php\PersonInterface and then call $sdk->migration()->migratePersons($persons);, for instance:

The $response will have the response of the endpoint POST /persons/bulk-import, i.e., an array with three keys:

• successful_imports - the number of persons that have successfully imported
• failed_imports - the number of failures during the import
• failed_csv - a CSV that reports the users that failed to import and the error reason for each line

Token Abstraction

The token abstraction is a class to help validating and manipulating the token used for authentication.

Validating token

To validate an authentication token, use the method validateToken:

Getting the person ID from the token

To get the Person ID (the "sub" in the token), use the method getSubFromToken:

Webhook Abstraction

The webhook abstraction is a class to help work with webhooks, for creating, listing, and deleting them, and also adding and removing triggers.

You can access it with:

Listing webhooks

The method findAll() lists all existing webhook listeners in the organization, including listeners in other applications and environments:

The method findById($id) fetches one single webhook when you have its ID.

The method findByUrl($url) fetches one single webhook when you have its URL.

Creating webhooks and setting triggers

The register($url, $name, $triggers, $options) method is idempotent, i.e., it will either create a webhook if it doesn't exist yet or update it if there is already a webhook with that URL. After creating or updating the webhook, it will also register triggers for it. Thus, this method combines calls to /organizations/webhooks and /organizations/webhooks/:webhook_id/triggers endpoints.

A few notes:

1. The $triggers argument is a list of triggers the webhook will have. For the full list see: https://developer.slashid.dev/docs/access/guides/webhooks/introduction
2. If the webhook is being updated, the $triggers will override existing triggers.

3. The $options argument is a list of additional fields the /organizations/webhooks endpoint receives (see https://developer.slashid.dev/docs/api/post-organizations-webhooks), e.g.:

4. If the webhook is being updated, the $options will NOT override existing values, unlike $triggers.

A few examples:

Setting triggers

You can also handle triggers directly.

The method setTriggers($id, $triggers) will override existing triggers, deleting triggers that are not in the $triggers list and adding new ones that are not.

The method addWebhookTrigger($id, $trigger) adds one single trigger from a webhook.

The method deleteWebhookTrigger($id, $trigger) removes one single trigger from a webhook.

Deleting webhooks

You can delete a webhook with either the deleteById($id) or deleteByUrl($url) methods.

Webhook callback

After you register a webhook and add triggers, SlashID servers will start sending requests to your endpoint. The request will be a JWT that you will have to decode and validate, using keys provided by an API endpoint using the JSON Web Signature standard.

Since the JWT Key Set (JWKS) must be downloaded remotely, it's important to cache the keys in order not to keep making remote requests all the time. So, when calling decodeWebhookCall, you have to a PSR-6-compatible \Psr\Cache\CacheItemPoolInterface object.

Some frameworks provide PSR-6 implementations by default:

• Laravel: app('cache.psr6')
• Symfony: package symfony/cache

For other frameworks, check this list: https://packagist.org/providers/psr/cache-implementation

To implement a webhook listener, fetch the encoded JWT from the body of the remote request, then call decodeWebhookCall to have it validated and decoded. Here's an example of a Laravel implementation that dispatches an Event after receiving the webhook.