Using the REST API

1. Authentication

The SPScan REST API uses Laravel Sanctum tokens for authentication. To generate an API token, navigate to your account settings in the SPScan dashboard and click "Create API Token". Give the token a descriptive name that reflects its intended use, such as "Monitoring Script" or "CI Pipeline". The token will be displayed once and cannot be retrieved afterwards, so store it securely.

Include the token in every API request using the Authorization header with the Bearer scheme. For example: Authorization: Bearer your-token-here. All API requests must also include the Accept: application/json header to ensure responses are returned in JSON format.

API access requires an active subscription or trial. If your subscription expires, API requests will return a 403 Forbidden response. You can create multiple tokens for different integrations and revoke them individually from the account settings page. We recommend using separate tokens for each integration so that revoking one does not break others.

2. Available Endpoints

The SPScan API is available at /api/v1/ and provides endpoints for managing tenants, querying sites, viewing permissions, and accessing alert data. All endpoints return JSON responses and follow RESTful conventions with standard HTTP status codes for success and error responses.

The tenants endpoint (GET /api/v1/tenants) returns a list of all connected tenants with their current compliance scores, site counts, and storage usage. You can retrieve detailed information for a specific tenant using GET /api/v1/tenants/{id}. The sites endpoint (GET /api/v1/tenants/{id}/sites) lists all discovered sites within a tenant.

The permissions endpoint (GET /api/v1/tenants/{id}/permissions) returns all permission entries for a tenant, including direct permissions, sharing links, and external access. The alerts endpoint (GET /api/v1/tenants/{id}/alerts) provides a history of triggered alerts. All list endpoints support pagination using page and per_page query parameters.

3. Querying Permissions

The permissions endpoint supports several filter parameters that allow you to narrow down results to specific types of permissions. Use type=external to retrieve only external sharing permissions, type=anonymous for anonymous access links, or type=direct for directly assigned permissions.

You can also filter by site using the site_id parameter, which is useful when you want to audit a specific site's permissions programmatically. The since parameter accepts an ISO 8601 timestamp and returns only permissions that were created or modified after that date, which is helpful for incremental synchronisation workflows.

Each permission entry in the response includes the resource path, the principal (user, group, or link type), the permission level (read, write, full control), and metadata about when the permission was first detected and last seen. This data structure gives you everything you need to build custom dashboards, generate reports, or feed permission data into your own security tools.

4. Triggering Scans

You can trigger an on-demand scan for any connected tenant using the POST /api/v1/tenants/{id}/sync endpoint. This queues a full scan of the tenant, which includes site discovery, storage analysis, permission scanning, and compliance scoring. The endpoint returns a 202 Accepted response with a job identifier that you can use to check the scan status.

Scans are processed asynchronously on the scanning queue. A full scan can take several minutes depending on the size of the tenant. You can check the status of a scan using GET /api/v1/tenants/{id}/sync/{job_id}, which returns the current status (queued, processing, completed, or failed) and any results or error messages.

Programmatic scans are useful for integrating SPScan into CI/CD pipelines or automation workflows. For example, you might trigger a scan after making changes to SharePoint sharing policies to verify that the changes had the intended effect. You can also use the sync endpoint in combination with the permissions endpoint to build a workflow that scans, waits for completion, and then retrieves the updated permission data.

5. Rate Limits and Best Practices

The SPScan API enforces rate limits to ensure fair usage and system stability. The default rate limit is 60 requests per minute per API token. If you exceed the rate limit, the API will return a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before making another request.

To avoid hitting rate limits, we recommend implementing exponential backoff in your API clients. When you receive a 429 response, wait for the duration specified in the Retry-After header, then retry your request. For batch operations that require many API calls, use pagination efficiently by requesting larger page sizes (up to 100 items per page) to reduce the total number of requests.

When building integrations, cache API responses where appropriate to minimise unnecessary requests. Permission data changes only when a scan completes, so there is no need to poll the permissions endpoint more frequently than your scan interval. Use the since parameter for incremental queries, and consider using webhooks instead of polling for real-time event notifications.