Skip to main content

ggshield auth login


Authenticate with a GitGuardian instance.

ggshield auth login [OPTIONS]

A successful authentication results in a personal access token. This token is stored in your configuration and used to authenticate your future requests.

The default authentication method is web. ggshield launches a web browser to authenticate you to your GitGuardian instance, then automatically generates a token on your behalf.

Alternatively, you can use --method token to authenticate using an already existing token. The minimum required scope for the token is scan.

By default, the created token will have the scan scope. Use the --scopes option to grant the token extra scopes. You can find the list of available scopes in GitGuardian API documentation.

If a valid personal access token is already configured, this command simply displays a success message indicating that ggshield is already ready to use.


  • --method [token|web]: Authentication method.

    Default: web.

  • --instance URL: URL of the instance to authenticate against.

  • --scopes SCOPES: Space-separated list of extra scopes to request in addition to the default scan scope.

  • --sso-url URL: URL of your SSO login page to force the authentication flow through your workspace SSO.

  • --token-name TEXT: Name of new token.

  • --lifetime DAYS: Number of days before the token expires. 0 means the token never expires. [x>=0]

This command supports all ggshield global options.


# start interactive web-based flow
$ ggshield auth login

# force the authentication flow through a SSO
$ ggshield auth login --sso-url

# specify the name of the personal access token about to be provisioned
$ ggshield auth login --token-name mytoken

# authenticate with an already existing token, ggshield will prompt you to enter the token
$ ggshield auth login --method=token
Enter your GitGuardian API token: <type your token and press enter>

# authenticate against a self-hosted GitGuardian instance
$ ggshield auth login --instance https://dashboard.gitguardian.mycorp.local

How can I help you ?