# Authentication Methods for Grok Build Provider in Grok2API: OAuth 2.0 Implementation Guide

> Explore Grok2API authentication for Grok Build provider. Learn about OAuth 2.0 authorization code and device flows. Master token refresh for secure access.

- Repository: [Chenyme/grok2api](https://github.com/chenyme/grok2api)
- Tags: how-to-guide
- Published: 2026-07-16

---

**Grok Build accounts in Grok2API authenticate exclusively using OAuth 2.0, supporting the standard authorization code flow, device authorization flow, and automatic token refresh, with no SSO support available.**

The Grok2API project provides a unified interface for interacting with Grok AI services, and understanding the authentication methods for the Grok Build provider is essential for secure API integration. According to the chenyme/grok2api source code, the Grok Build provider implements a strict OAuth 2.0-only authentication model with specific credential handling requirements.

## OAuth 2.0 Authentication Overview for Grok Build

The Grok Build provider defines its authentication surface in [`backend/internal/infra/provider/definition.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/definition.go) and [`backend/internal/infra/provider/cli/definition.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/cli/definition.go), explicitly declaring OAuth as the sole supported method.

### Exclusive OAuth 2.0 Support

Grok Build accounts are configured with the following credential properties:

- **AuthType**: Set to `account.AuthTypeOAuth` (OAuth 2.0 only)
- **Import**: `true` — credentials can be imported from OAuth token responses
- **Refresh**: `true` — long-lived refresh tokens are supported and automatically rotated
- **DeviceOAuth**: `true` — implements the OAuth device-authorization flow used by the Grok CLI

Any attempt to authenticate using SSO (single sign-on) will be rejected by validation logic in the provider definition. The [`web/sso_build.go`](https://github.com/chenyme/grok2api/blob/main/web/sso_build.go) file confirms that SSO paths are explicitly excluded for Grok Build and reserved only for the Web provider.

### Supported OAuth Flows

The Grok2API implementation includes three primary OAuth mechanisms:

1. **Standard Authorization Code Flow** — Used when performing web-based logins through a browser
2. **Device Authorization Flow** — The CLI obtains a device code, users authorize it in a browser, and the client polls for the token
3. **Automatic Token Refresh** — The system detects expired access tokens and uses stored refresh tokens to obtain new credentials

## Implementing OAuth 2.0 Authentication in Grok2API

The authentication logic is implemented across the CLI adapter and OAuth client modules within the `backend/internal/infra/provider/cli/` directory.

### Creating Credential Seeds from OAuth Tokens

When initializing a Grok Build account, you must create a `CredentialSeed` from the OAuth token response. In [`backend/internal/infra/provider/cli/adapter.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/cli/adapter.go) at line 360, the provider constructs the seed as follows:

```go
seed := provider.CredentialSeed{
    Name:            "My Grok Build Account",
    Email:           userEmail,
    UserID:          userID,
    TeamID:          teamID,
    OIDCClientID:    provider.DefaultOAuthClientID, // "b1a00492‑073a‑47ea‑816f‑4c329264a828"
    AccessToken:    tokens.AccessToken,
    RefreshToken:   tokens.RefreshToken,
    ExpiresAt:      tokens.ExpiresAt,
}

```

This seed captures the essential OAuth credentials including the default client ID `b1a00492‑073a‑47ea‑816f‑4c329264a828`, access tokens, refresh tokens, and expiration timestamps required for subsequent API calls.

### Device Authorization Flow Implementation

For CLI-based authentication, Grok2API implements the OAuth device flow in [`backend/internal/infra/provider/cli/oauth.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/cli/oauth.go) (lines 31-44 and 108-124). This flow is essential for headless environments where browser redirection is not possible:

```go
// Initialise the OAuth client that knows the device endpoint URLs
oauth := newOAuthClient(http.DefaultClient)

// Start the device flow – the server returns a verification URI and user code
devAuth, err := oauth.StartDeviceAuthorization(ctx, "openid profile email offline_access grok-cli:access api:access")
if err != nil {
    // Handle initialization error
}

// Show the user the verification URL and code (CLI prints them)
// Then poll until the token is issued
tokens, err := oauth.PollDeviceToken(ctx, devAuth.DeviceCode)
if err != nil {
    // Handle polling error
}

```

The device flow requires the scope `"openid profile email offline_access grok-cli:access api:access"` and handles the polling mechanism automatically until the user completes authorization in their browser.

### Automatic Token Refresh

The gateway service in [`backend/internal/application/gateway/service.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/application/gateway/service.go) (line 434) implements automatic token refresh to maintain long-lived sessions:

```go
// The gateway service checks for stale credentials and refreshes them
if cred.AuthType == account.AuthTypeOAuth && cred.RefreshToken != "" {
    newCred, err := oauth.RefreshToken(ctx, cred.RefreshToken)
    if err == nil {
        // Persist the new access/refresh tokens
        accountRepo.UpdateCredential(ctx, newCred)
    }
}

```

This automatic refresh mechanism ensures that Grok2API operations continue uninterrupted without requiring manual re-authentication when access tokens expire.

## Why SSO Is Not Supported for Grok Build

The Grok Build provider explicitly validates that the credential `AuthType` is OAuth, rejecting any other authentication method. While the Web provider (handled separately in [`web/sso_build.go`](https://github.com/chenyme/grok2api/blob/main/web/sso_build.go)) supports SSO integration, the Grok Build CLI provider ([`backend/internal/infra/provider/cli/definition.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/cli/definition.go)) enforces OAuth-only constraints at the infrastructure level. This architectural decision ensures consistent authentication behavior across CLI environments and prevents credential type confusion between web and build contexts.

## Summary

- **Grok Build uses OAuth 2.0 exclusively** — no SSO or other authentication methods are supported
- **Three OAuth flows are available**: standard authorization code, device authorization, and automatic refresh
- **Key implementation files** include [`backend/internal/infra/provider/cli/adapter.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/cli/adapter.go) for credential creation and [`backend/internal/infra/provider/cli/oauth.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/cli/oauth.go) for OAuth client operations
- **Automatic token refresh** is handled by [`backend/internal/application/gateway/service.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/application/gateway/service.go) to maintain session continuity
- **Device authorization** enables CLI authentication without browser redirection on the local machine

## Frequently Asked Questions

### What authentication type does Grok Build use in Grok2API?

Grok Build uses **OAuth 2.0 exclusively** with the `account.AuthTypeOAuth` type. The provider definition in [`backend/internal/infra/provider/cli/definition.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/cli/definition.go) validates that credentials must be OAuth-based, and any attempt to use other authentication methods will raise an error during validation.

### How does the device authorization flow work for Grok Build?

The device flow involves calling `StartDeviceAuthorization()` to obtain a verification URI and user code, displaying these to the user, then polling with `PollDeviceToken()` until authorization completes. This implementation in [`backend/internal/infra/provider/cli/oauth.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/cli/oauth.go) allows CLI tools to authenticate users without requiring a local browser or callback server.

### Does Grok Build support automatic token refresh?

Yes, Grok Build supports **automatic token refresh** using long-lived refresh tokens. The gateway service automatically detects expired access tokens and uses the stored refresh token to obtain new credentials, persisting the updated tokens via `accountRepo.UpdateCredential()` without requiring user intervention.

### Can I use SSO credentials with Grok Build provider?

No, SSO credentials are **not supported** for Grok Build. While the Web provider in [`backend/internal/infra/provider/web/sso_build.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/provider/web/sso_build.go) handles SSO authentication, the Grok Build provider explicitly rejects SSO attempts. You must use OAuth 2.0 tokens obtained through either the authorization code flow or device authorization flow.