Authentication

All authenticated API calls require a Bearer token in the Authorization header.

API Key (Bearer Token)

The simplest way to authenticate is with an API key. You can set your own API key by logging into sheepCRM and navigating to Profile settings.

Once you have a key, include it as a Bearer token in the Authorization header:

http https://api.sheepcrm.com/api/v1/$FLOCK/ Authorization:"Bearer $API_KEY"

For convenience, export your key as an environment variable:

export API_KEY=my-secret-api-key
export FLOCK=example

Then you can use the variables directly in httpie commands:

http https://api.sheepcrm.com/api/v1/$FLOCK/ Authorization:"Bearer $API_KEY"

A successful response returns HTTP 200 with a list of available resources. A 403 FORBIDDEN response indicates a problem with your API key or permissions.

OAuth2 Client Registration

For applications that need to authenticate users via OAuth2 (e.g. website single sign-on), you must register your application as an OAuth client.

Prerequisites

Register your application

Navigate to https://auth.sheepcrm.com/o/applications/
Register the client with the following settings:

Field	Description
Client Name	A human-readable name shown in messages like “{Client Name}” wants to access your information
Client Type	Choose `confidential`
Authorization grant type	Choose `Authorization code`
Redirect URIs	Provide one callback URL that will retrieve an access token. It must be a valid URL using `https://`. Your website plugin or system will tell you the value to use.
Flock	The sheepCRM database identifier. Required unless the client is for multiple Sheep databases.
Logo	A secure (`https`) URL to a square logo, used during the login process.
Security Policy	A secure (`https`) URL to your application’s security policy.
Terms and Conditions	A secure (`https`) URL to your application’s terms and conditions.
Your contact details	Not made public; used by sheepCRM to communicate with you about your integration.

A Client ID and Client Secret are returned — keep these safe.

Configure your OAuth client

Use the Client ID and Secret with the following endpoints:

Endpoint	URL
Authorization	`https://auth.sheepcrm.com/o/authorize/`
Token	`https://auth.sheepcrm.com/o/token/`
User information	`https://iam.sheepcrm.com/userinfo/`
Token URL method	`POST`

Available scopes

Scope	Description
`read`	View profile information: `first_name`, `last_name`, `photo`
`write`	Update profile
`read_membership`	View membership information: `active_member`, `membership_type`, `membership_start_date`, `membership_end_date`
`introspection`	Introspect token scope

Optional authorization parameters

Parameter	Description
`flock`	Your Sheep database identifier. Required if the client is for multiple Sheep databases.
`approval_prompt`	`force` — users are always prompted for authorization. `auto` — users are prompted only the first time; subsequent authorizations for the same application and scopes are automatically accepted.