How many flat connections has a line bundle in algebraic geometry? Suppose $X$ is a projective variety over $\mathbb C$.  I am happy to entertain more or different adjectives — I'm not looking for the most general statement, but rather to understand when and how smooth-manifold intuition leads me astray.  I know very little algebraic geometry, and so please forgive and correct me if a statement below is mistaken.
It is rare for a line bundle $\mathcal L \to X$ to have a nowhere-vanishing section, and when it does, there are usually very few (only $\mathbb C^\times$ many).
Suppose instead that I ask for a weaker structure than for $\mathcal L$ to have a section, but rather let me ask only that it has a flat connection.  My question is:

In algebraic geometry, how often does a line bundle have a flat connection?  When it has a flat connection, how many flat connections can it have?

 A: I presume that your variety $X$ is smooth.
Consider the additive map $\mathrm d\log \colon \mathscr O_X^*\to \Omega^1_X$ that sends $f$ to $\mathrm df/f$. It induces a map $c_1$ in cohomology from $H^1(X,\mathscr O_X^*)$
to $H^1(X,\Omega^1_X)$ — a coherent avatar of the first Chern class.
By Hodge Theory, $H^1(X,\Omega^1_X)$ is a subspace of $H^2(X,\mathbf C)$ and the two notions
of first Chern class coincide.  
A line bundle $\mathscr L$ has a connection if and only if its first Chern class $c_1(\mathscr L)\in H^1(X,\Omega^1_X)$ vanishes. The proof is straightforward: take an open cover $(U_i)$ of $X$, an invertible section $s_i$ of $\mathscr L$ on $U_i$ and the associated cocycle $(f_{ij})$ representing your line bundle in $H^1(X,\mathscr O_X^*)$. A connection $\nabla$ maps $s_i$ to $s_i\otimes\omega_i$, for some 1-form $\omega_i\in H^0(U_i,\Omega^1_X)$. The condition that these $s_i\otimes\omega_i$ come from a global connection on $X$ is exactly the vanishing of $c_1(\mathscr L)$.
It is a non-trivial fact that if $\mathscr L$ has an algebraic connection, then it is automatically flat. Torsten Ekedahl gave an algebraic proof on this thread of MO
(Ekedahl also observes that $p$th power of line bundles in characteristic $p$ have an integrable connection), but an analytic proof seems easy. The algebraic connexion $\nabla$ gives rise to a connexion $\nabla+\bar\partial$ on the associated holomorphic line bundle. One checks that the curvature of this connection is a $(2,0)$-form, while it should be a $(1,1)$-form. Consequently, it vanishes. 
When non empty, the set of flat connections on a vector bundle $\mathscr E$ is an affine space under $H^0(X,\Omega^1_X\otimes\mathscr E\mathit{nd}(\mathscr E))$, a finite dimensional vector space. In our case, $\mathscr L$ is a line bundle, hence $\mathscr E\mathit{nd}(\mathscr L)$ is the trivial line bundle so that we get $H^0(X,\Omega^1_X)$.
NB. Following the comment of Ben McKay, I edited the last paragraph.
A: A vector bundle with an algebraic connection has to have vanishing all Chern classes, at least in characteristic zero. I remember that this follows from the vanishing of the "Atiyah class", but I don't know the details.  
A: Question: "In algebraic geometry, how often does a line bundle have a flat connection? When it has a flat connection, how many flat connections can it have?"
Comment: Over other fields/rings than the complex number field you get similar results using basic properties of the $\operatorname{Ext}$ and $\operatorname{Hom}$ functors: If $\pi: X \rightarrow S:=Spec(A)$ is any scheme and if $L\in Pic(X)$ is any invertible sheaf, there is the Atiyah-sequence
$$A1.\text{  } 0 \rightarrow \Omega^1_{X/S} \otimes L \rightarrow J^1(L) \rightarrow L \rightarrow 0$$
which is split iff $L$ has a connection. You get an extension class
$$a(L) \in \operatorname{Ext}^1_{\mathcal{O}_X}(L, L\otimes \Omega^1_{X/S}) \cong $$
$$  \operatorname{Ext}^1_{\mathcal{O}_X}(\mathcal{O}_X, L^*\otimes L\otimes \Omega^1_{X/S}) \cong  \operatorname{Ext}^1_{\mathcal{O}_X}( \mathcal{O}_X, \Omega^1_{X/S}) \cong $$
$$ \operatorname{H}^1(X, \Omega^1_{X/S}).$$
You may view the image of the class $a(L)=c_1(L)$ under the above isomorphisms as  the first Chern class of $L$. Hence $c_1(L)=0$ iff $L$ has a connection. The set of connections on $L$ is parametrized by the set
$$\operatorname{Hom}_{\mathcal{O}_X}(L, L \otimes \Omega^1_{X/S}) \cong $$
$$\operatorname{Hom}_{\mathcal{O}_X}(\mathcal{O}_X,\operatorname{Hom}_{\mathcal{O}_X}(L, L \otimes \Omega^1_{X/S})) \cong $$
$$\operatorname{Hom}_{\mathcal{O}_X}(\mathcal{O}_X, L^*\otimes L \otimes \Omega^1_{X/S}) \cong $$
$$\operatorname{Hom}_{\mathcal{O}_X}(\mathcal{O}_X,  \Omega^1_{X/S}) \cong \operatorname{H}^0(X, \Omega^1_{X/S}).$$
More generally if $E$ is any locally trivial finite rank sheaf you get a class
$$a(E) \in \operatorname{H}^1(X, \operatorname{End}_{\mathcal{O}_X}(E) \otimes \Omega^1_{X/S}).$$
with the same properties. The "parameter-space of connections" is the set
$$\operatorname{H}^0(X, \operatorname{End}_{\mathcal{O}_X}(E) \otimes \Omega^1_{X/S}).$$
Remark: You may let $S$ be any base-scheme and the above results still hold.
The following link gives an obstruction sequence for a general $E$ to have a flat connection using non-abelian extensions of (sheaves of) Lie-Rinehart algebras:
When do flat holomorphic connections exist?
When $E$ is a locally trivial finite rank sheaf with a connection $\nabla$, there is an exact sequence
$$0 \rightarrow \operatorname{End}_{\mathcal{O}_X}(E) \rightarrow \Theta_X(E, \nabla) \rightarrow \Theta_X \rightarrow 0$$
which splits iff $E$ has a flat connection. By definition
$$ \Theta_X(E, \nabla):= \operatorname{End}_{\mathcal{O}_X}(E)\oplus \Theta_X$$
with  the following Lie-structure:
If $x,y \in \Theta(U)$ and $\phi, \psi \in \operatorname{End}_{\mathcal{O}_X}(E)(U)$, define
$$ [(\phi,x),(\psi,y)]:=([\phi,\psi]+[\nabla(x), \psi]-[\nabla(y), \phi]+R_{\nabla}(x,y), [x,y]),$$
where $R_{\nabla}$ is the curvature of $\nabla$.
Note: When you add a potential $P$ to a flat connection $\nabla$, it does not follow that the new connection $\nabla+P$ is flat.
Example: If $X\subseteq \mathbb{P}^n_{\mathbb{C}}$ is a smooth quasi projective variety with a finite rank locally trivial sheaf $E$ with an algebraic connection $\nabla$, you get an extension class
$$na(E,\nabla) \in \operatorname{Ext}^1(\Theta_X, \operatorname{End}_{\mathcal{O}_X}(E))$$
and there is a canonical map
$$c:\operatorname{Ext}^1(\Theta_X, \operatorname{End}_{\mathcal{O}_X}(E)) \rightarrow \operatorname{H}^1(X, \operatorname{End}_{\mathcal{O}_X}(E) \otimes \Omega^1_X),$$
with $na(E,\nabla)="0"$ iff $E$ has a flat algebraic connection $\nabla':=\nabla+P$. The two classes $c(na(E,\nabla))$ and $a(E)$ live in the same vector space. One may wonder if these two classes are related: If $c(na(E,\nabla))$ is a multiple of $a(E)$, it follows $a(E)=0$ may imply $na(E,\nabla)=0$. The "non-abelian cohomology set"
$$\operatorname{Ext}^1(\Theta_X, \operatorname{End}_{\mathcal{O}_X}(E))$$
does not have the structure of an abelian group in general. I believe it has been conjectured that if $a(E)=0$ it follows $na(E,\nabla)=0$ but do not have a precise reference.
Example: For a line bundle it follows $\operatorname{End}(L) \cong \mathcal{O}_X$ and you get an exact sequence
$$NA.\text{  }0 \rightarrow \mathcal{O}_X \rightarrow \Theta_X(L, \nabla)  \rightarrow \Theta_X \rightarrow 0.$$
By the above argument it follows this sequence splits over the complex numbers.
Example: Let for simplicity $L\in \operatorname{Pic}(A)$ be an invertible $A$-module with a connection  $\nabla: T \rightarrow \operatorname{End}_k(L)$ with $T:=\operatorname{Der}_k(A)$.
Let $ad\nabla: T \rightarrow \operatorname{End}_k(L^* \otimes_A L) \cong \operatorname{End}_k(A)$.
It follows for any endomorphism $\phi_a \in L^*\otimes L$ we have
$$ad\nabla(x)(\phi_a)=\phi_{x(a)},$$
where $\phi_a(u):=au$ for $u\in L$. It follows $ad\nabla$ is a flat connection. We get an extension
$$NA1.\text{  } 0 \rightarrow L^* \otimes L \rightarrow L^* \otimes L \oplus T \rightarrow^p T \rightarrow 0$$
where the middle term has the following Lie structure:
$$[(a,x),(b,y)]:=(x(b)-y(a) +R_{\nabla}(x,y),[x,y])$$
for $a,b\in L^* \otimes L, x,y \in T$.
Lemma: A section $s: T\rightarrow A\oplus T$
with $s(x):=(\rho(x),x)$ is $A$-linear and a map of $k$-Lie algebras iff the map $\nabla^*:=\nabla+\rho$ is a flat connection.
Hence sequence $A1$ is the obstruction for the existence of a connection and $NA1$ is the obstruction for the existence of a flat connection.
If $(L,\nabla)$ is a flat connection on a line bundle $L$ it follows sections $\rho$ of $NA$ are in 1-1 correspondence with flat connections $\nabla^*:=\nabla+\rho$. Hence you may view the "set of sections" of $NA$ as the "parameter-space of flat connections". There is an algebraic group/a group scheme acting on this parameter space and you may form the "(stack) quotient".
If $X$ is a complex projective manifold it follows $NA$ should have a section for any $L\in Pic(X)$.
Note: Let $X \subseteq \mathbb{P}^n_S$ be projective over $S:=Spec(A)$ with $A$ a finitely generated algebra over a field $k$ and let $E$ be a coherent $\mathcal{O}_X$-module. It follows
$$\operatorname{H}^0(X, \operatorname{End}(E)\otimes \Omega^1_{X/S})$$
is a finitely generated $A$-module. This is Hartshorne, Thm II.5.19. In particular if $A$ equals $k$, it follows the group is a finite dimensional $k$-vector space.
Note: The field $k$ may be arbitrary, hence the results are valid for a real algebraic variety $X$ and a finite rank vector bundle $E$ on $X$. The "Serre-Swan theorem" gives an equivalence of categories between the category of real smooth finite rank vector bundles on a real smooth manifold $M$ and finite rank projective $R:=C^{\infty}(M)$-modules. The ring $R$ is a commutative unital algebra over the field of real numbers, and the sequences $A1,NA1$ exist for any $R$-module $L$.
