Skip to main content

​
About LinkedIn

LinkedIn is a professional network with REST APIs covering member profiles, organization (Company) pages, advertising, and Matched Audiences. Serval connects through a bring-your-own-app model: your team registers its own app in the LinkedIn Developer portal and supplies that app’s Client ID and Primary Client Secret in Serval’s Connect modal. Because Serval does not own a shared LinkedIn app, your team controls exactly which LinkedIn products, permissions, and rate-limit budget the connection uses. Workflow requests go only to LinkedIn’s official API host (api.linkedin.com). Authentication: Bring-your-own LinkedIn app using the OAuth 2.0 authorization code flow. You pick which permissions to request, register Serval’s redirect URL on your app, and enter your Client ID and Primary Client Secret. Data sync: On demand only - there is no background sync. Workflows call the LinkedIn REST API at run time, and Serval injects and automatically refreshes the access token for you (LinkedIn access tokens last about 60 days by default; refresh tokens, where available, about 365 days).

​
What the LinkedIn integration enables

Anything defined in the LinkedIn API can be accessed through Serval.

​
Get your credentials

You need your own LinkedIn OAuth app with the right products approved, its scopes enabled, and Serval’s redirect URL registered. Everything happens in the LinkedIn Developer portal.
1

Create (or open) your LinkedIn app

Go to the LinkedIn Developer portal and click Create app, or open an existing app. Associate a LinkedIn Company Page - LinkedIn gates many products on the app being linked to a verified Company Page.
2

Request the products you need

On the Products tab, click Request access next to the products matching the permissions you will select in Serval (Share on LinkedIn, Advertising API, Community Management API, and so on). LinkedIn must approve each product before its permissions work - some are auto-approved, others are reviewed and can take days. Connect Serval only after the products show under Added products.
3

Approve the OAuth scopes

On the Auth tab, under OAuth 2.0 scopes, approve the scopes for the products you added. You will pick the matching subset in Serval’s Connect modal - Serval only requests what you select.
4

Register Serval's redirect URL

Still on the Auth tab, under Authorized redirect URLs for your app, paste the exact Redirect URL shown in Serval’s Connect modal and click Update. The URL is environment specific - always use the value from the modal, never a hand-constructed one.
5

Copy your credentials

From the Auth tab, copy the Client ID and the Primary Client Secret into Serval’s Connect modal.
Do not click Generate a new Client Secret on LinkedIn after connecting. LinkedIn invalidates the previous secret immediately, which breaks Serval’s automatic token refresh until you reconnect with the fresh secret.
LinkedIn uses a two-layer permission model: products (Products tab) grant the right to use scopes (Auth tab). A scope can be approved and still fail until the backing product appears under Added products.

​
Connect in Serval

The Connect modal has two steps: Permissions, then Connect.
1

Step 1: Permissions - choose what Serval requests

Check the permission bundles that match the products your LinkedIn app has. Sign In with LinkedIn is shown checked and disabled with the tag “Always included” - it is requested on every connection. The bundles are convenience groupings, not a strict one-to-one product map (some scopes are granted by more than one LinkedIn product), so you can also expand All permissions and search individual scopes (search placeholder: “Search all LinkedIn permissions…”) to add a single scope without taking a whole bundle. Serval requests only what you select; an unrecognized scope is rejected with “unsupported LinkedIn scope: [scope]”.
Only select permissions your LinkedIn app actually has enabled. Requesting even one scope the app lacks fails the entire authorization with LinkedIn’s unauthorized_scope_error.
2

Step 2: Connect - register the redirect URL

The modal displays a read-only Redirect URL with a Copy button (it toggles to “Copied”). Helper text: “Add this as an Authorized redirect URL in your LinkedIn app’s Auth tab.” Register it on your LinkedIn app before continuing.
3

Enter your connection details

All three fields are required: the Connect to LinkedIn button stays disabled until every field is filled, the form refuses to submit without them (“Please fill in all required fields”), and blank values are also rejected server-side (“appName is required”, “clientId is required”, “clientSecret is required”).
  • Connection name (required) - a Serval-side label only. Helper text: “The name that will identify this connection in Serval. We recommend using your LinkedIn app name.” LinkedIn does not expose your app’s display name to Serval, so you choose it.
  • Client ID (required) - from your LinkedIn app’s Auth tab.
  • Primary Client Secret (required, hidden password field) - from your LinkedIn app’s Auth tab.
4

Authorize on LinkedIn

Click Connect to LinkedIn and approve the consent screen. Complete it within 10 minutes - Serval holds your pending credentials only that long, after which you will see “Invalid or expired OAuth state” or “OAuth session expired, please try again” and need to restart the flow.
There is no separate edit-credentials form. To update the secret or pick up newly approved permissions, run the Connect flow again with the same Client ID - the existing connection is updated in place (the connection is keyed on the Client ID), your workflows are preserved, and the permission picker is pre-seeded with the scopes the connection currently has so you do not accidentally downgrade. A different Client ID creates a separate connection.

​
Verifying the connection

The LinkedIn integration ships three health checks:
  • Test LinkedIn Connection - verifies Serval can authenticate by fetching the connected member’s basic profile.
    • Success: “Successfully connected to LinkedIn as [name]”
    • Failure: “Unable to connect to LinkedIn. Verify your OAuth credentials are valid, the app has the r_basicprofile scope approved, and the token has not been revoked.”
  • Get 1st-degree Connection Count - verifies the Connection insights permission by fetching the member’s total 1st-degree connections.
    • Success: “Authenticated member has [number] 1st-degree connection(s).” or, when LinkedIn omits the count, “API access verified but LinkedIn did not return a connection count. The scope is approved but the member may not have any connections exposed.”
    • Product-gating failure: “Your LinkedIn app has the r_1st_connections_size scope approved, but the /v2/connections endpoint requires the app to also be enrolled in the LinkedIn Marketing Developer Platform program. Apply for the program from your LinkedIn app’s Products tab - once approved, this check will pass without needing to reconnect.”
    • Generic failure: “Unable to fetch connection count. Verify your LinkedIn app has the r_1st_connections_size scope approved on the Auth tab.”
  • List Administered Organizations - verifies the organization-admin permission by listing organizations the member administers.
    • Success: “Found [number] administered organization(s).” or, with zero results, “API access verified but this member does not administer any organizations.”
    • Failure: “Unable to list organizations. Verify your LinkedIn app has the r_organization_admin or rw_organization_admin scope approved.”
A green Test LinkedIn Connection with failures elsewhere almost always means product gating: basic profile access works on every live connection, but other calls fail until the backing LinkedIn product is approved under Added products. Once LinkedIn approves the product, the failing checks pass without reconnecting.

​
Gotchas and troubleshooting

LinkedIn products gate scopes. A scope checked on the Auth tab appears on the consent screen and in the granted list, yet calls return 403 until the backing product is under Added products on the Products tab. The clearest example: the connection-count check fails with LinkedIn’s ACCESS_DENIED error when the Connection insights scope is approved but the app is not enrolled in the Marketing Developer Platform program. Apply for the missing product from the Products tab - once approved, calls succeed without reconnecting.
You selected a permission in step 1 that your LinkedIn app does not have enabled. LinkedIn fails the entire authorization, not just the one scope. Restart the Connect flow and select only the bundles matching the products your app actually has, or enable the missing scope on the app’s Auth tab first.
Serval holds the credentials you submit in the Connect modal for only 10 minutes between clicking Connect to LinkedIn and finishing LinkedIn’s consent screen. Taking longer shows “Invalid or expired OAuth state” or “OAuth session expired, please try again”. Just restart the Connect flow.
The Client ID or Primary Client Secret does not match a live LinkedIn app credential. Re-copy both values from your app’s Auth tab - and if someone clicked Generate a new Client Secret, the old secret is already invalid and you must reconnect with the new one.
Serval refreshes access tokens using the Client ID and secret stored with the connection. Generating a new Client Secret on LinkedIn invalidates the previous one immediately, so refresh fails until you reconnect with the fresh secret. Reconnecting with the same Client ID updates the existing connection in place. Note that refresh tokens only exist when your app is enrolled in LinkedIn’s refresh token program; otherwise reconnect when the access token expires (about 60 days).
LinkedIn grants the Advertising API at a Development tier first, with tighter limits on accessible ad accounts and request volume. If advertising calls work in testing but hit limits in production, apply for the Standard tier from your app’s Products tab on LinkedIn. This is LinkedIn-side behavior and approval is at LinkedIn’s discretion.
LinkedIn retired its legacy ad-account discovery calls, which now return errors. Use the integration’s ad-account discovery capability instead, which runs on LinkedIn’s current versioned Marketing API. Serval automatically attaches the protocol and version headers LinkedIn’s versioned API requires, so you never set them yourself.
When a workflow creates a Matched Audience segment, LinkedIn returns the new segment’s ID in a response header rather than the response body, and update or delete operations return an empty success response. Only the segment’s name, description, access policy, and source segment can be updated. Populating a segment with members uses LinkedIn’s separate CSV list-upload process, which is not available through this integration’s API action.
Need help? Contact support@serval.com for assistance with your LinkedIn integration.