Integration with your app

Since a graphapi® operates like a standard GraphQL server, an app developer can use numerous libraries and frameworks for integration. The integration process requires common steps irrespective of the used API client.

You can find an excessive list of GraphQL clients on the GraphQL Foundation's GraphQL Tools Overview page (opens new window).

GraphQL URL

Each GraphQL client expects a single URL endpoint typically ending with /graphql for communicating with the GraphQL server. The graphapi GraphQL endpoint is found in the blue URL widget or on the graphapi settings page. When performing an API request, the client has to pass a valid authentication header with an API Key or a valid access token.

Authentication

When performing an API request, the client has to pass a valid authentication header with an API Key or a valid access token.

TIP

Only use API Key authentication during development or where it is safe to expose data publicly.

Creating API keys

The default API Key on the API settings page should not be exposed outside your workspace. Creating a custom API Key for each client application is always recommended. By doing so, you can revoke access to one key without affecting other clients. For security reasons, API keys expire by default after 365 days.

1. Click the Create custom API keys section on the API settings page to create a new API key.
2. Click the Add GraphApi Key button, provide a meaningful name, and optionally set the expiration time.
3. After clicking Create the API Key is ready to use. You can get it from the API Keys section and use it in your client app.

TIP

Pass the API key through an HTTP Header, e.g., "x-api-key: da2-sb72abcdefghijklmnopq23".

AWS Cognito Authentication

If you select AWS Cognito for user authentication, you need to integrate the Auth class from the AWS Amplify SDK. The following section shows a custom Auth class written in Typescript, wrapping some of the Amplify Auth functionality.

TIP

Create a Cognito user in your workspace before testing the following code.

import { Auth as CognitoAuth } from "aws-amplify";

export const getDefaultAuthConfig = () => ({
  region: "eu-central-1",
  userPoolId: "eu-central-1_jzA2xxxx",
  userPoolWebClientId: "3lg644234sdfdsfowerljldsfo3lk234",
  authenticationFlowType: "USER_PASSWORD_AUTH",
});

export interface IAuthConfig {
  region: string;
  userPoolId: string;
  userPoolWebClientId: string;
  authenticationFlowType: string;
}

export class Auth {
  public getUserSession(user: CognitoUserExt) {
    return new Promise<CognitoUserSession>((res, rej) => {
      user.getSession((error: Error, session: CognitoUserSession | null) => {
        if (error || !session) {
          rej(error);
        } else {
          res(session);
        }
      });
    });
  }

  public configure(config: IAuthConfig = getDefaultAuthConfig()) {
    CognitoAuth.configure(config);
  }

  public async initialize(): Promise<IUserAndSession> {
    if (process.env.NODE_ENV !== "testing") {
      this.configure();
    }

    const user: CognitoUserExt = await CognitoAuth.currentAuthenticatedUser();
    const session = await this.getUserSession(user);

    return { user, session };
  }

  public async signIn(credentials: ICredentials): Promise<IUserAndSession> {
    const user: CognitoUserExt = await CognitoAuth.signIn(
      credentials.username,
      credentials.password
    );
    const session = await this.getUserSession(user);

    return {
      user,
      session,
    };
  }
}

// Get a valid access token
try {
  const auth = new Auth();
  auth.configure();
  const { user, session } = await auth.signIn(credentials);
  const cognitoAccessToken = session?.getAccessToken();
} catch (err) {
  // handle error
}