Collaborators

Collaborator attributes

field	type	description
id	string	unique ID
email	string	email address
user_id	string	unique ID of the user who has accepted the collaboration
username	string	username (“n/a”: invitation is still pending)
tfa_status	boolean	“true” if the user has enabled multi-factor authentication, “false” otherwise
status	string	pending: invitation not yet accepted, accepted: invitation has been accepted
is_limited	boolean	collaborator have a limited role
invitation_link	string	invitation link. “” (empty string) if invitation has been accepted or user is limited
app_id	string	unique ID of the app the user is collaborating to
app_name	string	name of the app the user is collaborating to

Example object:

{
  "id": "54101e25736f7563d5060000",
  "email": "foo@example.com",
  "user_id": "us-8ba226e5-93e0-4545-8363-9c16b2d68d67",
  "username": "soulou",
  "tfa_status": true,
  "status": "accepted",
  "is_limited": false,
  "invitation_link": "",
  "app_id": "54100930736f7563d5030000",
  "app_name": "my-app"
}

List Collaborators of an App

GET https://$SCALINGO_API_URL/v1/apps/[:app]/collaborators

List all the collaborators of an app, except the owner. It also displays the state of the invitation of those collaborators.

Example Request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/apps/[:app]/collaborators

Returns 200 OK

{
  "collaborators": [
    {
      "id": "54101e25736f7563d5060000",
      "email": "foo@example.com",
      "user_id": "us-8ba226e5-93e0-4545-8363-9c16b2d68d67",
      "username": "soulou",
      "tfa_status": true,
      "status": "accepted",
      "is_limited": false,
      "invitation_link": "",
      "app_id": "54100930736f7563d5030000",
      "app_name": "my-app"
    },
    {
      "id": "54101e25736f7563d5060001",
      "email": "bar@example.com",
      "user_id": null,
      "username": "n/a",
      "tfa_status": null,
      "status": "pending",
      "is_limited": true,
      "invitation_link": "https://my.scalingo.com/apps/collaboration?token=abc",
      "app_id": "54100930736f7563d5030000",
      "app_name": "my-app"
    }
  ]
}

Update a Collaborator

PATCH https://$SCALINGO_API_URL/v1/apps/[:app_id]/collaborators/[:id]

Only the is_limited field is allowed to be modified. The endpoint does not allow changing email, status, or username. It’s not allowed to change the role of the SCM Linker.

Example Request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X PATCH https://$SCALINGO_API_URL/v1/apps/[:app]/collaborators/[:collaborator_id] \
  -d '{"collaborator": {"is_limited": true}}'

Returns 200 OK

{
  "collaborator": {
    "id": "54101e25736f7563d5060000",
    "email": "foo@example.com",
    "user_id": "us-8ba226e5-93e0-4545-8363-9c16b2d68d67",
    "username": "soulou",
    "tfa_status": true,
    "status": "accepted",
    "is_limited": true,
    "invitation_link": "",
    "app_id": "54100930736f7563d5030000",
    "app_name": "my-app"
  },
}

Invite Collaborator To Work on an App

POST https://$SCALINGO_API_URL/v1/apps/[:app]/collaborators

This action will create an invitation to the given person. You can invite either someone with an account on Scalingo or someone new. In the second case, they will be able to access the application after creating their account.

Note: An email will be sent to the invited user.

Note that the invitation_link returned by this call is not bound to the email of the invited collaborator. Hence you should never share this link publicly.

Parameters

collaborator.email: Email address of the collaborator to invite
collaborator.is_limited: Whether the collaborator should have limited access (default: true)

Example Request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X POST https://$SCALINGO_API_URL/v1/apps/[:app]/collaborators -d \
  '{
     "collaborator": {
       "email":"collaborator@example.com",
       "is_limited": false
      }
   }'

Returns 201 Created

{
  "collaborator": [
    {
      "id": "54101e25736f7563d5060000",
      "email": "collaborator@example.com",
      "user_id": null,
      "username": "n/a",
      "tfa_status": null,
      "status": "pending",
      "is_limited": false,
      "invitation_link": "https://my.scalingo.com/apps/collaboration?token=abc",
      "app_id": "54100930736f7563d5030000",
      "app_name": "my-app"
    }
  ]
}

Accept an Invitation to Collaborate

GET https://$SCALINGO_API_URL/v1/apps/collaboration?token=[:token]

This action accepts an invitation to collaborate on an app. The token is given in the invitation_link returned when adding a new collaborator.

Example Request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/apps/collaboration?token=8415965b809c928c807dc99790e5745d97f05b8c

Returns 200 OK

{
  "app": {
    "id": "54100930736f7563d5030000",
    "name": "example-app",
    "created_at": "2014-09-10T10:17:52.690+02:00",
    "updated_at": "2014-09-10T10:17:52.690+02:00",
    "git_url": "git@scalingo.com:example-app.git",
    "last_deployed_at": "2017-02-02T10:17:53.690+02:00",
    "last_deployed_by": "john",
    "last_deployment_id": "58c2b15af1453a0001e24d23",
    "force_https": true,
    "sticky_session": false,
    "router_logs": true,
    "owner": {
      "username": "john",
      "email": "user@example.com",
      "id": "54100245736f7563d5000000"
    },
    "url": "https://example-app.scalingo.io",
    "links": {
      "deployments_stream": "wss://deployments.scalingo.com/apps/example-app"
    }
  }
}

Delete a Collaborator

DELETE https://$SCALINGO_API_URL/v1/apps/[:app]/collaborators/[:collaborator_id]

This action completely remove a collaborator from an app. Only the owner of the app can execute it. The user won’t be able to access, nor to deploy it.

Example Request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X DELETE https://$SCALINGO_API_URL/v1/apps/[:app]/collaborators/54101e25736f7563d5060000

Returns 204 No Content

List owned applications collaborators

GET https://$SCALINGO_API_URL/v1/collaborators

List all collaborators assigned to any application owned by the current user.

Example Request

curl -H "Accept: application/json" -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -X GET https://$SCALINGO_API_URL/v1/collaborators

Returns 200 OK

{
  "collaborators": [
    {
      "id": "54101e25736f7563d5060000",
      "email": "foo@example.com",
      "user_id": "us-8ba226e5-93e0-4545-8363-9c16b2d68d67",
      "username": "soulou",
      "tfa_status": true,
      "status": "accepted",
      "is_limited": false,
      "invitation_link": "",
      "app_id": "54100930736f7563d5030000",
      "app_name": "my-app"
    },
    {
      "id": "54101e25736f7563d5060001",
      "email": "bar@example.com",
      "user_id": null,
      "username": "n/a",
      "tfa_status": null,
      "status": "pending",
      "is_limited": true,
      "invitation_link": "https://my.scalingo.com/apps/collaboration?token=abc",
      "app_id": "54100930736f7563d5030000",
      "app_name": "my-app"
    },
    {
      "id": "54101e25736f7563d5060000",
      "email": "foo@example.com",
      "user_id": "us-8ba226e5-93e0-4545-8363-9c16b2d68d67",
      "username": "soulou",
      "tfa_status": true,
      "status": "accepted",
      "is_limited": true,
      "invitation_link": "",
      "app_id": "24100930736f7563d5030099",
      "app_name": "another-app"
    },
  ]
}