Skip to content
English
More support Ticket overview
  • There are no suggestions because the search field is empty.

Scoping of data API access

Overview

When integrating with the Shoreline API, it’s essential to ensure that API credentials can access only the specific data they need.
This guide explains how to properly scope API access following the principle of least privilege.

Understanding Shoreline API Access Control

Shoreline’s API uses a project-based authentication model, which means:

  • API data access is granted through projects

  • API credentials are used to authenticate against that specific project

How to Scope API Access

Step 1: Use Project-Level Scoping

All Shoreline API operations are project-scoped using the projectId parameter.

Finding your Project ID

  1. Navigate to Account Settings → Integrations → Ingestion API

  2. Copy the projectId for the specific project you want the API to access

In your API calls:

{
  "projectId": "your-project-id-here",
  "workOrders": [...],
  ...
}

By using a specific projectId, your API integration will only interact with that project’s data.

Step 2: Secure Token Management

Authenticate

POST /authenticate
Content-Type: application/json

{
  "username": "api-integration-erp",
  "password": "secure-password"
}

Response

{
  "token": "eyJhbGc..."
}

Important Security Practices

  • Store the token securely (e.g., environment variables or a secrets manager)

  • Do not hardcode tokens in source code

  • Refresh tokens periodically when they expire

  • Rotate API user passwords regularly

Step 3: Test and Validate Access

Verify that scoping works correctly

  1. Test data access

    • Try to export data from projects the API user should not have access to

    • Expected result: Receive authorization errors or empty results

  2. Monitor API usage

    • Regularly review which operations the API user performs

    • Ensure actions align with the intended scope

Example: Read-Only Integration for Project X

Scenario: You want to create a Power BI integration that can read work orders from Project Alpha.

Setup

  1. Ask Shoreline Support to create an API credential set named:
    api-powerbi-readonly

  2. Assign permissions:

    • Access only to Project Alpha

  3. Get Project ID: proj-alpha-12345 (from Account Settings)

  4. Use this configuration in your integration code:

// Authenticate
const authResponse = await fetch('https://ex.your-subdomain.shoreline.no/api/authenticate', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    username: 'api-powerbi-readonly',
    password: process.env.SHORELINE_API_PASSWORD
  })
});

const { token } = await authResponse.json();

// Export work orders (scoped to Project Alpha only)
const exportResponse = await fetch('https://ex.your-subdomain.shoreline.no/api/export/workorders', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
    'accept': 'application/json'
  },
  body: JSON.stringify({
    projectId: 'proj-alpha-12345',
    changedSince: '2025-01-01T00:00:00Z'
  })
});

const { correlationId } = await exportResponse.json();

// ... continue with async flow

Common Questions

Q: Can one API user access multiple projects?
A: An API user can either access all projects or a single project.
Inform Shoreline Support of your preference — we strongly recommend restricting API users to single-project access.

Q: What happens if I use the wrong projectId?
A: If the API user doesn’t have access to that project, the API will return authorization errors or no data.
Always validate your projectId values.

Q: How do I revoke API access?
A: Contact Shoreline Support to have API credentials for a given user revoked.

Security Checklist

  • ✅ Using specific projectId values in API calls

  • ✅ Storing credentials securely (not in source code)

  • ✅ Tested that scoping works as expected

  • ✅ Documented which API user is used for each integration

  • ✅ Set up a regular password rotation schedule

Need Help?

If you need assistance setting up scoped API access or have questions about permissions: