SDKS

PHP SDK

The WorkOS PHP SDK provides your applications convenient access to the WorkOS SSO API.

Installation

To get started, install the WorkOS PHP SDK via Composer by running:

Terminal

file_copy
composer require workos/workos-php

View the source on GitHub.


Configuration

To use the SDK you must first provide your API key and Project ID from the Developer Dashboard:

PHP

file_copy
\WorkOS\WorkOS::setApiKey(getenv('WORKOS_API_KEY'));
\WorkOS\WorkOS::setProjectId(getenv('WORKOS_PROJECT_ID'));

SSO

The SSO Class provides convenient functions for interacting with the WorkOS SSO product.

SSO->getAuthorizationUrl()

Generate an Authorization URL to intitiate the WorkOS OAuth 2.0 flow.

SSO->getAuthorizationUrl accepts the following arguments:

  • $domain (null|string) - Domain of the user that will be going through SSO
  • $redirectUri (null|string) - URI to direct the user to upon successful completion of SSO
  • $state (null|array) - Associative array containing state that will be returned from WorkOS as a JSON encoded string
  • $provider (null|\WorkOS\Resource\ConnectionType) - Service provider that handles the identity of the user

Returns:

  • string

Example:

app.php

file_copy
$url = (new \WorkOS\SSO())->getAuthorizationUrl(
  'my-co.com',
  {redirectURI},
  null,
  null
);

SSO->getProfile()

Fetch a \WorkOS\Resource\Profile for an authenticated user.

SSO->getProfile accepts the following arguments:

  • $code (string) - Code returned by WorkOS on completion of authorization flow

Returns:

  • \WorkOS\Resource\Profile

Example:

app.php

file_copy
$profile = (new WorkOSSSO())->getProfile($code)

SSO->createConnection()

Create a Connection.

SSO->createConnection accepts the following arguments:

  • $source (string) - Token returned by WorkOS as a result of the WorkOS.js embed workflow.

Returns:

  • \WorkOS\Resource\Connection

Example:

app.php

file_copy
$connection = $sso->createConnection($token);

AuditTrail

The AuditTrail Class provides convenient functions for accessing the WorkOS Audit Trail product.

AuditTrail->createEvent()

Create an Audit Trail event.

AuditTrail->createEvent accepts the following arguments:

  • $event (array) - Array representing an Audit Trail event of the form:
    • $event["action_type"] (string) - Corresponding CRUD category of event. Can be one of C, R, U, or D.
    • $event["actor_name"] (string) - Display name of the entity performing the action.
    • $event["actor_id"] (string) - Unique identifier of the entity performing the action.
    • $event["group"] (string) - A single organization containing related members. This will normally be the customer of a vendor's application.
    • $event[l"ocation"] (string) - Identifier for where the event originated. This will be an IP address (IPv4 or IPv6), hostname, or device ID.
    • $event["occurred_at"] (string) - ISO-8601 datetime at which the event happened, with millisecond precision.
    • $event["metadata"] (string) - Arbitrary key-value data containing information associated with the event. Note: There is a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.
    • $event["target_id"] (string) - Unique identifier of the object or resource being acted upon.
    • $event["target_name"] (string) - Display name of the object or resource that is being acted upon.
  • $idempotencyKey (string) - Unique key guaranteeing idempotency of events for 24 hours.

Returns:

  • boolean

Example:

app.php

file_copy
$now = (new DateTime())->format(DateTime::ISO8601);

$event = [
    "group" => "organization_id",
    "action" => "user.login",
    "action_type" => "C",
    "actor_name" => "[email protected]",
    "actor_id" => "user_id",
    "target_name" => "[email protected]",
    "target_id" => "user_id",
    "location" =>  "1.1.1.1",
    "occurred_at" => $now,
];

(new WorkOSAuditTrail())->createEvent($event);

AuditTrail->getEvents()

Filter for Audit Trail Events.

AuditTrail->getEvents accepts the following arguments:

  • $group (null|string|array) - Group or array of groups to filter for
  • $action (null|string|array) - Action of array of actions to filter for
  • $actionType (null|string|array) - Action type of array of action types to filter for
  • $actorName (null|string|array) - Actor name or array of actor names to filter for
  • $actorId (null|string|array) - Actor ID or array of action IDs to filter for
  • $targetName (null|string|array) - Target name or array of target names to filter for
  • $targetID (null|string|array) - Target ID or array of target IDs to filter for
  • $occurredAt (string) - ISO-8601 datetime of when an event occurred
  • $occurredAtGt (string) - ISO-8601 datetime of when an event occurred after
  • $occurredAtGte (string) - ISO-8601 datetime of when an event occurred at or after
  • $occurredAtLt (string) - ISO-8601 datetime of when an event occurred before
  • $occurredAtLte (string) - ISO-8601 datetime of when an event occured at or before
  • $search (string) - Keyword search
  • $limit (int) - Number of Events to return
  • $before (string) - Event ID to look before
  • $after (string) - Event ID to look after

Returns:

  • array
    • string - Before cursor
    • string - After cursor
    • array - \WorkOS\Resource\Event

Example:

app.php

file_copy
list($before, $after, $events) = (new WorkOSAuditTrail())->getEvents();

DirectorySync

The DirectorySync Class provides convenient functions for interacting with the WorkOS Directory Sync product.

DirectorySync->listDirectories()

List Directories.

DirectorySync->listDirectories accepts the following arguments:

  • $domain (null|string) - Domain of a Directory
  • $search (null|string) - Searchable text for a Directory
  • $limit (int) - Maximum number of records to return
  • $before (null|string) - Pagination cursor to receive records before a provided ID
  • $after (null|string) - Pagination cursor to receive records after a provided ID

Returns:

  • array
    • string - Before cursor
    • string - After cursor
    • array - \WorkOS\Resource\Directory

Example:

app.php

file_copy
list($before, $after, $directories) = (new WorkOSDirectorySync())->listDirectories();

DirectorySync->listGroups()

List Directory Groups.

DirectorySync->listGroups accepts the following arguments:

  • $directory (null|string) - Directory ID
  • $user (null|string) - Directory User ID
  • $limit (int) - Maximum number of records to return
  • $before (null|string) - Pagination cursor to receive records before a provided ID
  • $after (null|string) - Pagination cursor to receive records after a provided ID

Returns:

  • array
    • string - Before cursor
    • string - After cursor
    • array - \WorkOS\Resource\DirectoryGroup

Example:

app.php

file_copy
list($before, $after, $groups) = (new WorkOSDirectorySync())->listGroups();

DirectorySync->getGroup()

Get a Directory Group.

DirectorySync->getGroup accepts the following arguments:

  • $directoryGroup (string) - Directory Group ID

Returns:

  • \WorkOS\Resource\DirectoryGroup

Example:

app.php

file_copy
$group = (new WorkOSDirectorySync())->getGroup("directory_grp_id");

DirectorySync->listUsers()

List Directory Users.

DirectorySync->listUsers accepts the following arguments:

  • $directory (null|string) - Directory ID
  • $group (null|string) - Directory Group ID
  • $limit (int) - Maximum number of records to return
  • $before (null|string) - Pagination cursor to receive records before a provided ID
  • $after (null|string) - Pagination cursor to receive records after a provided ID

Returns:

  • array
    • string - Before cursor
    • string - After cursor
    • array - \WorkOS\Resource\DirectoryUser

Example:

app.php

file_copy
list($before, $after, $users) = (new WorkOSDirectorySync())->listUsers();

DirectorySync->getUser()

Get a Directory User.

DirectorySync->getUser accepts the following arguments:

  • $directoryUser (string) - Directory User ID

Returns:

  • \WorkOS\Resource\DirectoryUser

Example:

app.php

file_copy
$user = (new WorkOSDirectorySync())->getUser("directory_user_id");

Resources

\WorkOS\Resource\Profile

An instance of \WorkOS\Resource\Profile will have attributes and values similar to the following:

JSON

file_copy
{
  "connectionType": "OktaSAML",
  "email": "[email protected]{foo-corp.com}",
  "firstName": "User",
  "id": "prof_id",
  "idpId": "randomalphanum",
  "lastName": "Name"
}

\WorkOS\Resource\Connection

An instance of \WorkOS\Resource\Connection will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "conn_id",
  "domains": [
    [
      "id": "conn_dom_id",
      "domain": "foo-corp.com"
    ]
  ],
  "status": "linked",
  "name": "Foo Corp Okta",
  "connectionType": "OktaSAML",
  "oauthUid": null,
  "oauthSecret": null,
  "oauthRedirectUri": "http://my-co.com/sso/provider/callback",
  "samlEntityId": null,
  "samlIdpUrl": null,
  "samlRelyingPartyTrustCert": null,
  "samlX509Certs": null
}

\WorkOS\Resource\Directory

An instance of \WorkOS\Resource\Directory will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_id",
  "externalKey": "external-key",
  "state": "linked",
  "type": "gsuite directory",
  "name": "user",
  "bearerToken": null,
  "projectId": "project_id",
  "domain": "foo-corp.com",
}

\WorkOS\Resource\DirectoryGroup

An instance of \WorkOS\Resource\DirectoryGroup will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_grp_id",
  "name": "Developers"
}

\WorkOS\Resource\DirectoryUser

An instance of \WorkOS\Resource\Directory will have attributes and values similar to the following:

JSON

file_copy
{
  "id": "directory_id",
  "externalKey": "external-key",
  "state": "linked",
  "type": "gsuite directory",
  "name": "user",
  "bearerToken": null,
  "projectId": "project_id",
  "domain": "foo-corp.com",
}