Skip to main content
Version: 2.0

Endpoint Authorization

Security Context

Authorization for GraphGrid API endpoints is primarily determined by client and user roles, though some endpoints do use OAuth2 scopes. A list of endpoints and required roles is available here.


In this document, a "client" will refer to an OAuth API client with an associated client id/secret. Clients are used to obtain an authorization grant and access token, which users can then use to make API requests.

If you would like to check the roles and scope associated with an OAuth token, the check token endpoint can be used to examine the token's security context. When authenticating using user credentials and the /1.0/security/oauth/token endpoint, client credentials are also required. Any roles associated with the client id and secret used will then become associated with the user's OAuth token. For example, if a client with ROLE_CLIENT_INTERNAL is used to authenticate a user with ROLE_USER, the returned OAuth token will have a security context with both ROLE_CLIENT_INTERNAL and ROLE_USER.

Please note that security groups and roles are completely different. Security groups are used to enforce authorization requirements for dynamic Showme endpoints in GraphGrid's Manager service. Roles are used for authorization throughout GraphGrid with non-Showme endpoints.

Roles for users accounts can be modified by users with the role ROLE_SUPER_ADMIN using these endpoints. While API clients can be created, deleted, and updated using these endpoints, modifying roles require connecting to the LDAP service directly.


GraphGrid uses OpenLDAP to hold user and client credentials. Before trying to connect, please ensure the openldap service has port 389 exposed. We recommend using Apache Directory Studio to connect to the LDAP server. Connect using "Simple Authentication" with cn=admin,dc=graphgrid,dc=com as the "Bind DN". The LDAP admin password can be found in the GraphGrid data directory in data/env/openldap.env.

Roles exist in LDAP as group membership attributes. User roles can be modified using the previously mentioned endpoints, or by changing group membership directly in LDAP. Client roles can only be modified through LDAP.

Default Client

The default client that ships with GraphGrid has publicly exposed credentials to accommodate requests from the GraphGrid Curator dashboard. We highly recommend locking down or removing the default client, and creating one with a new secret that fits your specific organizational needs. Some endpoints can be called with a client_credentials grant type, so please keep that in mind when determining your client roles.

If you do end up changing your client credentials, you'll need to provide your updated credentials to the Curator dashboard. The dashboard code is stored inside the custom NGINX image that ships with GraphGrid. Simply copy the file at /var/www/viz/config.js (inside the NGINX container), and override it using a Docker bind mount.