Access Tokens and App Passwords
Some programs cannot sign in the way a person does. A script that calls the CityScreen Deals API has no browser, and a mail client that reads the company directory has no screen for a second factor. CityScreen Deals gives each employee two credentials for these programs, and both are created in the Account section.
| Credential | Used by | Accepted at |
|---|---|---|
Personal access token |
Scripts and local tools that call the API |
The REST API |
App password |
A mail client or another program that reads the company directory over LDAP |
LDAP sign-in |
Both credentials belong to the employee who created them. Each is shown once, when it is created, and cannot be shown again, so an employee who loses the value creates a new one. Both are revoked at any time, and each one is revoked on its own.
To open them, click your name in the top-right header to reach the Account section, and select the tab Access Tokens or App passwords. A tab appears when your role has the matching permission and the license includes the function. Both tabs list only your own entries.
Personal access tokens
A personal access token lets a script or a local tool call the CityScreen Deals REST API with your access. It works until it expires or you revoke it.
This function is licensed. If your organization’s license does not include it, contact CityScreen.
What you need
Your role needs the permission Personal access tokens. The action View shows the tab, Create adds the button Create token, and Delete adds the button Revoke. An administrator grants these in the role editor, see Roles & Permissions.
Creating a token
-
Open Account > Access Tokens and click Create token.
-
Enter a Name that tells you what the token is for, for example "CI pipeline". The name is required and can have up to 255 characters.
-
Choose the Lifetime. For Custom date, pick the Expiration date.
-
Click Create.
-
The dialog Token created shows the token once, with the warning "Copy the token now. It will not be shown again. Treat it like a password." Click Copy, store the token where the program can read it, and click Done.
The token starts with csd_pat_.
The list shows its first characters under the name, so that you can tell your tokens apart.
Creating a token needs a web sign-in. A token cannot create tokens or app passwords, change the password or the username, or set up two-step verification.
Lifetime
The Lifetime field offers 30 days (preselected), 90 days, 1 year, No expiration and Custom date. An administrator can set a Maximum access token lifetime of 1 to 3650 days in Settings > General. With a maximum, the field offers only the choices that fit within it, adds the maximum itself as a choice (for example 45 days) when no other choice equals it, and drops No expiration.
Custom date stays available and accepts dates up to the maximum. The field then shows a hint such as "Maximum allowed: 45 days". Without a maximum, a token may be created with no expiration.
CityScreen Deals checks the maximum only when a token is created. Lowering it later leaves existing tokens as they are.
The list
The list shows these columns for each token.
| Column | Content |
|---|---|
Name |
The name, with the first characters of the token under it. |
Created |
The creation date. |
Expires |
The expiration date, or Never. |
Last used |
The date and the IP address of the last call, or Never used. |
Status |
Active, or Expired once the expiration date has passed. |
What a token can do
A token acts with your own permissions, and CityScreen Deals looks them up again at every call. A change to your roles or groups therefore applies to your tokens at once, and a token never holds more than you do. Tokens have no scopes of their own.
A token works for as long as your account is active, your organization is active, the token has not expired, and the license includes the function. Changing, resetting or expiring your account password leaves your tokens working.
App passwords
An app password is a separate password for one mail client or one other program that signs in over LDAP. Create one for each program, so that you can revoke it on its own and your account password stays out of every device.
This function is licensed. If your organization’s license does not include it, contact CityScreen.
What an app password is for
An app password is accepted only at LDAP sign-in. The web application, the REST API and the other entry points refuse it.
An app password has no expiration date. It works until you revoke it or your account is deactivated.
An employee who has two-step verification can sign in over LDAP only with an app password, because LDAP has no step for a verification code.
The same holds when your organization requires two-step verification of you before you have set it up, and when your account password has expired. The account password is refused at LDAP sign-in in all three cases, and an app password keeps working. See Two-Step Verification for the setup.
Changing or resetting your account password leaves app passwords working. LDAP sign-in is itself part of the license, and without it no program can sign in over LDAP, whatever the credential.
What you need
Your role needs the permission App passwords. The action View shows the tab, Create adds the button Create app password, and Delete adds the button Revoke.
Creating an app password
-
Open Account > App passwords and click Create app password.
-
Enter a Name, for example "Thunderbird on my laptop". The name is required, can have up to 100 characters, and must differ from the names of your other app passwords, ignoring upper and lower case.
-
Click Create.
-
The dialog App password created shows the password once, with the warning "Copy the password now. It will not be shown again. Enter it in the mail client in place of a password." Click Copy, enter it in the mail client, and click Done.
An app password is created from a web sign-in, like a token.
The list shows the Name with the first characters of the password under it, the date it was Created, and Last used with the date and the address of the program, or Never used.
Settings for the mail client
Above the list, the panel Use in a mail client tells you what to enter.
| Field in the panel | What to enter |
|---|---|
Bind DN (user name) |
The user name of the mail client.
It has the form |
Base DN |
The root of the directory. |
Password |
An app password created on this page. |
Server |
|
The panel shows the Bind DN (user name) and the Base DN only to an employee whose role may view LDAP consumers. Everyone else sees the text "To set up a mail client, ask your administrator for the address of the LDAP server and the bind DN, and enter an app password as the password."
CityScreen can confirm the server address for your organization. See LDAP Directory for how the directory is built.
When an employee leaves
Deactivating an employee deletes all of their access tokens and app passwords together with their other credentials. See Employees.
What administrators can do
An administrator whose role has View and Delete on Personal access tokens and on App passwords for the whole organization can list and revoke any employee’s tokens and app passwords through the REST API, with GET and DELETE on /personal-access-tokens and /app-passwords.
Each employee creates their own tokens and app passwords.
Related pages
-
Your Account — the other tabs of the Account section
-
Two-Step Verification — why an employee with two-step verification needs an app password
-
LDAP Directory — the directory that app passwords sign in to
-
Password Policy and Sign-In Protection — the block after repeated failed sign-ins, which also covers LDAP
-
Organization Settings — the maximum access token lifetime
-
Roles & Permissions — granting the permissions for both credentials
-
Integrations — other ways to connect systems