Calling APIs using an Access Token

info

These directions assume you already have an access token — either from the Access Token Generator or from a 2-legged or 3-legged OAuth flow.

Vendasta APIs expect the token as a Bearer Token in the Authorization header:

Authorization: Bearer <access_token>

Your first call

The example below reads CRM field schemas for a namespace. It is a good first call because it only reads data, so it cannot change anything while you are getting set up.

Replace <access_token> with your token and AG-EXAMPLE with an account group ID you have access to.

curl -X POST 'https://demo.apigateway.co/grpc/v1/crm/field-schema/list' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "namespace": "AG-EXAMPLE",
    "crmObjectType": "Contact"
  }'

namespace is the only required field. crmObjectType narrows the result to one object type — omit it to get schemas across all of them.

A successful call returns 200 and the field schemas defined for that namespace:

{
  "fieldSchemas": [
    {
      "fieldId": "standard__email",
      "externalId": "standard__email",
      "fieldName": "Email",
      "fieldType": "FIELD_TYPE_EMAIL",
      "crmObjectType": "Contact"
    }
  ],
  "pagingMetadata": {
    "hasMore": true,
    "nextCursor": "..."
  }
}

tip

This call requires the crm.schema:read scope. If your token does not carry it you will get PERMISSION_DENIED — see Troubleshooting below. Each method's page in the API reference lists the scopes it needs.

Verifying a token

If you want to check what a token is before using it, call the SSO user-info endpoint. This requires the profile or email scope.

curl 'https://sso-api-prod.apigateway.co/oauth2/user-info' \
  --header 'Authorization: Bearer <access_token>'

{
  "sub": "U-d6f69389-350c-465e-ad8a-3c68447fb63a",
  "email": "automated-account-creation@partner-service-account.apigateway.co",
  "updated_at": 1591049766,
  "roles": [
    "partner_service_account"
  ],
  "created_at": 1591049766
}

Fields differ according to which scopes the token has.

Troubleshooting

code	Status	What to do
16	UNAUTHENTICATED	The token is missing, malformed, or expired. Generate a new one.
7	PERMISSION_DENIED	The token is valid but lacks the scope the method requires, or the account has no access to that namespace. Check the scopes on the method's reference page and reissue the token with them.
3	INVALID_ARGUMENT	The body was rejected. Read details — it names the specific field.
5	NOT_FOUND	The namespace or record does not exist in this environment. Confirm you are pointing at the right host.

Tokens are environment specific. A token issued for Demo will not work against Production, and vice versa.

See Errors for the full response shape.

Next steps

• Request Format — how requests and responses are structured
• API Reference — every method, with a built-in client for trying calls